clavix 4.11.1 → 4.12.0

package/README.md

@@ -1,5 +1,5 @@
 # Clavix
-> **Clavix Intelligence™** for AI coding. Transform rough ideas into production-ready prompts with automatic quality optimization—no framework to learn.
+> Prompt optimization for AI coding. Transform rough ideas into structured, actionable prompts using pattern-based analysis—no framework to learn.
 
 ## Table of contents
 - [Why Clavix?](#why-clavix)
@@ -20,24 +20,26 @@
 **Requirements:** Node.js ≥ 16.0.0 (ESM support required)
 
 ## Why Clavix?
-Better prompts lead to better code. Clavix automatically detects what you're trying to do and applies the right optimization patterns—no framework to learn, no methodology to master. Just describe what you want, and Clavix makes it AI-ready.
+Better prompts lead to better code. Clavix analyzes what you're trying to do and applies structured optimization patterns—no framework to learn, no methodology to master. Just describe what you want, and Clavix structures it for AI consumption.
 
-**What makes Clavix v3.0 unique:**
-- **95%+ Intent Detection Accuracy** - Weighted keyword scoring, phrase-based detection, and negation handling
-- **6 Production-Ready Optimization Patterns** - Automatically applied based on intent and quality assessment
-- **Zero Learning Curve** - Works with your natural language, adapts to your style
-- **Universal Integration** - Supports 20+ AI coding assistants with native slash commands
+**What Clavix provides:**
+- **Pattern-based intent detection** - Weighted keyword scoring across 11 intent categories
+- **20 optimization patterns** - Automatically applied based on intent and quality assessment
+- **Workflow management** - PRD generation, task breakdown, and implementation tracking
+- **Universal integration** - Supports 20+ AI coding assistants with native slash commands
 
 Learn more in [docs/why-clavix.md](docs/why-clavix.md).
 
 ## How It Works
-Clavix uses **Clavix Intelligence™** (v3.0+) to automatically:
-- **Detect intent** - 95%+ accuracy with weighted scoring, phrase detection, and context analysis
-- **Assess quality** - Evaluates across 5 dimensions: Clarity, Efficiency, Structure, Completeness, Actionability
-- **Apply patterns** - 6 optimization patterns automatically selected and prioritized for your specific need
-- **Generate output** - Production-ready prompts optimized for AI coding assistants
+Clavix uses pattern-based analysis to:
+- **Detect intent** - Keyword scoring and phrase detection across 11 intent categories
+- **Assess quality** - Heuristic scoring across 6 dimensions: Clarity, Efficiency, Structure, Completeness, Actionability, Specificity
+- **Apply patterns** - 20 optimization patterns automatically selected based on intent and quality
+- **Generate output** - Structured prompts optimized for AI coding assistants
 
-**The magic happens automatically**—no frameworks to learn, no manual analysis required. Just describe what you want in plain language, and Clavix transforms it into an AI-ready prompt using battle-tested optimization patterns.
+Optimization applies automatically—no frameworks to learn, no manual analysis required. Just describe what you want in plain language, and Clavix structures it into an AI-ready prompt.
+
+See [docs/philosophy.md](docs/philosophy.md) for an honest look at what Clavix is and isn't.
 
 ## Providers
 
@@ -55,11 +57,12 @@ Provider paths and argument placeholders are listed in [docs/integrations.md](do
 
 Most Clavix users work through AI coding assistants:
 
-> **💡 Choosing Your Mode:**
-> - **Fast/Deep** – Modifying or improving existing features
-> - **PRD** – Developing something completely new
+> **💡 Choosing Your Workflow:**
+> - **Improve** – Optimize a single prompt (auto-selects depth)
+> - **PRD** – Plan something new with guided questions
+> - **Start** – Explore ideas conversationally
 >
-> See [Choosing the Right Mode](docs/guides/workflows.md#choosing-the-right-mode) for detailed guidance.
+> See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
 
 ```bash
 # 1. Initialize in your project
@@ -67,23 +70,23 @@ npm install -g clavix
 clavix init
 
 # 2. Use slash commands in your AI agent
-/clavix:fast "Create a login page"
-/clavix:deep "Build an API for user management"
-/clavix:prd  # Full PRD workflow
+/clavix:improve "Create a login page"     # Optimize a prompt
+/clavix:prd                                # Full PRD workflow
+/clavix:start                              # Conversational exploration
 
 # 3. Manage saved prompts
 /clavix:execute  # Execute saved prompts
-/clavix:prompts  # Manage prompt lifecycle
+/clavix:verify   # Verify implementation against checklist
 
 # 4. Implement with task tracking
-clavix plan              # Generate tasks from PRD
-clavix implement         # Start implementation workflow
+/clavix:plan              # Generate tasks from PRD
+/clavix:implement         # Start implementation workflow
 clavix task-complete <taskId>  # Mark tasks done with auto-commit
 ```
 
 **Supported agents**: Claude Code, Cursor, Windsurf, and [17+ more providers](docs/integrations.md)
 
-Learn more: [Complete prompt lifecycle documentation](docs/commands/execute.md)
+Learn more: [Workflow guide](docs/guides/choosing-workflow.md)
 
 ### Direct CLI Usage (Alternative)
 
@@ -91,8 +94,8 @@ You can also use Clavix directly from the terminal:
 
 ```bash
 clavix init
-clavix fast "Create a login page"
-clavix deep "Build an API for user management"
+clavix improve "Create a login page"           # Auto-selects depth
+clavix improve --comprehensive "Complex API"   # Force comprehensive
 clavix prd
 ```
 
@@ -100,7 +103,8 @@ clavix prd
 - Overview & navigation: [docs/README.md](docs/README.md)
 - Command reference: [docs/commands/](docs/commands/README.md)
 - Providers: [docs/integrations.md](docs/integrations.md)
-- Clavix Intelligence: [docs/clavix-intelligence.md](docs/clavix-intelligence.md)
+- How it works: [docs/how-it-works.md](docs/how-it-works.md)
+- Philosophy: [docs/philosophy.md](docs/philosophy.md)
 - Guides: [docs/guides/](docs/guides/workflows.md)
 
 ## Requirements

package/dist/cli/commands/update.js

@@ -216,25 +216,24 @@ export default class Update extends Command {
 This project uses Clavix for prompt improvement and PRD generation.
 
 ### Available Commands
+- \`clavix improve [prompt]\` - Unified prompt optimization with auto-depth selection
+- \`clavix improve --comprehensive [prompt]\` - Force comprehensive analysis
+- \`clavix improve --standard [prompt]\` - Force standard optimization
+- \`clavix analyze [prompt]\` - JSON analysis output for programmatic use
 - \`clavix prd\` - Generate a comprehensive PRD through guided questions
-- \`clavix fast [prompt]\` - Quick prompt improvements with smart triage
-- \`clavix deep [prompt]\` - Comprehensive prompt analysis
 - \`clavix start\` - Start a conversational session for iterative development
 - \`clavix summarize\` - Extract requirements from conversation history
-- \`clavix list\` - List all sessions and outputs
-- \`clavix show [session-id]\` - Show detailed session information
+- \`clavix execute [--latest]\` - Execute saved prompts
+- \`clavix verify [--latest]\` - Verify implementation against checklist
 
 ### Quick Start
 \`\`\`bash
+# Prompt optimization (auto-selects depth)
+clavix improve "Build a user auth system"
+
 # Generate a PRD
 clavix prd
 
-# Quick prompt improvement
-clavix fast "Build a user auth system"
-
-# Deep prompt analysis
-clavix deep "Build a user auth system"
-
 # Start conversational mode
 clavix start
 \`\`\`

package/dist/core/intelligence/pattern-library.js

@@ -5,11 +5,9 @@ import { StructureOrganizer } from './patterns/structure-organizer.js';
 import { CompletenessValidator } from './patterns/completeness-validator.js';
 import { ActionabilityEnhancer } from './patterns/actionability-enhancer.js';
 // v4.0 Comprehensive scope patterns
-import { AlternativePhrasingGenerator } from './patterns/alternative-phrasing-generator.js';
-import { EdgeCaseIdentifier } from './patterns/edge-case-identifier.js';
-import { ValidationChecklistCreator } from './patterns/validation-checklist-creator.js';
-import { AssumptionExplicitizer } from './patterns/assumption-explicitizer.js';
-import { ScopeDefiner } from './patterns/scope-definer.js';
+// v4.12: Removed boilerplate patterns (AlternativePhrasingGenerator, EdgeCaseIdentifier,
+//        ValidationChecklistCreator, AssumptionExplicitizer, ScopeDefiner, ErrorToleranceEnhancer,
+//        PrerequisiteIdentifier) - these generated static output instead of improving prompts
 import { PRDStructureEnforcer } from './patterns/prd-structure-enforcer.js';
 // v4.0 Both scope patterns (standard & comprehensive)
 import { StepDecomposer } from './patterns/step-decomposer.js';
@@ -18,8 +16,6 @@ import { ContextPrecisionBooster } from './patterns/context-precision.js';
 import { AmbiguityDetector } from './patterns/ambiguity-detector.js';
 import { OutputFormatEnforcer } from './patterns/output-format-enforcer.js';
 import { SuccessCriteriaEnforcer } from './patterns/success-criteria-enforcer.js';
-import { ErrorToleranceEnhancer } from './patterns/error-tolerance-enhancer.js';
-import { PrerequisiteIdentifier } from './patterns/prerequisite-identifier.js';
 import { DomainContextEnricher } from './patterns/domain-context-enricher.js';
 // v4.3.2 PRD patterns
 import { RequirementPrioritizer } from './patterns/requirement-prioritizer.js';
@@ -73,29 +69,24 @@ export class PatternLibrary {
     }
     registerDefaultPatterns() {
         // Register core patterns (available in standard & comprehensive scopes)
-        this.register(new ConcisenessFilter()); // HIGH - Remove verbosity
-        this.register(new ObjectiveClarifier()); // HIGH - Add clarity
-        this.register(new TechnicalContextEnricher()); // MEDIUM - Add technical details
-        this.register(new StructureOrganizer()); // HIGH - Reorder logically
-        this.register(new CompletenessValidator()); // MEDIUM - Check missing elements
-        this.register(new ActionabilityEnhancer()); // HIGH - Vague to specific
+        // v4.12: 20 patterns total after removing 7 boilerplate patterns
+        this.register(new ConcisenessFilter()); // P10 - Remove verbosity
+        this.register(new ObjectiveClarifier()); // P9 - Add clarity
+        this.register(new TechnicalContextEnricher()); // P8 - Add technical details
+        this.register(new StructureOrganizer()); // P8 - Reorder logically
+        this.register(new CompletenessValidator()); // P6 - Check missing elements
+        this.register(new ActionabilityEnhancer()); // P7 - Vague to specific
         // v4.0 Comprehensive scope patterns
-        this.register(new AlternativePhrasingGenerator()); // P5 - Generate alternative structures
-        this.register(new EdgeCaseIdentifier()); // P4 - Identify edge cases by domain
-        this.register(new ValidationChecklistCreator()); // P3 - Create validation checklists
-        this.register(new AssumptionExplicitizer()); // P6 - Make implicit assumptions explicit
-        this.register(new ScopeDefiner()); // P5 - Add scope boundaries
+        // v4.12: Removed boilerplate patterns that generated static output
         this.register(new PRDStructureEnforcer()); // P9 - Ensure PRD completeness
         // v4.0 Both scope patterns (standard & comprehensive)
         this.register(new StepDecomposer()); // P7 - Break complex prompts into steps
         this.register(new ContextPrecisionBooster()); // P8 - Add precise context when missing
         // v4.1 New patterns - Agent transparency & quality improvements
         this.register(new AmbiguityDetector()); // P9 - Identify ambiguous terms (both scopes)
-        this.register(new OutputFormatEnforcer()); // P7 - Add output format specs (both scopes)
+        this.register(new OutputFormatEnforcer()); // P7 - Add output format specs (comprehensive only)
         this.register(new SuccessCriteriaEnforcer()); // P6 - Add success criteria (both scopes)
-        this.register(new ErrorToleranceEnhancer()); // P5 - Add error handling (comprehensive only)
-        this.register(new PrerequisiteIdentifier()); // P6 - Identify prerequisites (comprehensive only)
-        this.register(new DomainContextEnricher()); // P5 - Add domain best practices (both scopes)
+        this.register(new DomainContextEnricher()); // P5 - Add domain best practices (comprehensive only)
         // v4.3.2 PRD patterns
         this.register(new RequirementPrioritizer()); // P7 - Separate must-have from nice-to-have
         this.register(new UserPersonaEnricher()); // P6 - Add user context and personas

package/dist/core/intelligence/quality-assessor.d.ts

@@ -30,6 +30,26 @@ export declare class QualityAssessor {
      * Penalizes vague language, rewards concrete indicators
      */
     private assessSpecificity;
+    /**
+     * Calculate weighted overall quality score
+     * v4.12: Added comprehensive weight documentation
+     *
+     * WEIGHT RATIONALE:
+     * Weights are designed based on what matters most for each intent type:
+     *
+     * | Intent | Primary Focus | Secondary Focus | Rationale |
+     * |--------|---------------|-----------------|-----------|
+     * | code-generation | completeness (25%) | clarity, actionability (20% each) | Code needs full specs |
+     * | planning | structure, completeness (25% each) | clarity (20%) | Plans need organization |
+     * | debugging | actionability, completeness (25% each) | specificity (20%) | Need steps to reproduce |
+     * | migration | specificity, completeness (25% each) | clarity (20%) | Version/path precision |
+     * | testing | completeness (25%) | specificity, actionability (20% each) | Edge cases matter |
+     * | security-review | completeness (25%) | specificity, clarity (20% each) | Thorough coverage |
+     * | learning | clarity (30%) | structure, completeness (20% each) | Understanding > action |
+     * | default | completeness (22%) | clarity, structure, actionability (18% each) | Balanced |
+     *
+     * These weights can be overridden via ClavixConfig.intelligence.qualityWeights
+     */
     private calculateOverall;
     private identifyStrengths;
     private identifyImprovements;

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

@@ -292,8 +292,28 @@ export class QualityAssessor {
         }
         return Math.max(0, Math.min(100, score));
     }
+    /**
+     * Calculate weighted overall quality score
+     * v4.12: Added comprehensive weight documentation
+     *
+     * WEIGHT RATIONALE:
+     * Weights are designed based on what matters most for each intent type:
+     *
+     * | Intent | Primary Focus | Secondary Focus | Rationale |
+     * |--------|---------------|-----------------|-----------|
+     * | code-generation | completeness (25%) | clarity, actionability (20% each) | Code needs full specs |
+     * | planning | structure, completeness (25% each) | clarity (20%) | Plans need organization |
+     * | debugging | actionability, completeness (25% each) | specificity (20%) | Need steps to reproduce |
+     * | migration | specificity, completeness (25% each) | clarity (20%) | Version/path precision |
+     * | testing | completeness (25%) | specificity, actionability (20% each) | Edge cases matter |
+     * | security-review | completeness (25%) | specificity, clarity (20% each) | Thorough coverage |
+     * | learning | clarity (30%) | structure, completeness (20% each) | Understanding > action |
+     * | default | completeness (22%) | clarity, structure, actionability (18% each) | Balanced |
+     *
+     * These weights can be overridden via ClavixConfig.intelligence.qualityWeights
+     */
     calculateOverall(scores, intent) {
-        // v4.0: Intent-specific weights including specificity
+        // v4.0: Intent-specific weights (see rationale in method comment above)
         if (intent.primaryIntent === 'code-generation') {
             // Code generation benefits most from specificity
             return (scores.clarity * 0.2 +

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

@@ -2,6 +2,7 @@ import { IntentDetector } from './intent-detector.js';
 import { PatternLibrary } from './pattern-library.js';
 import { QualityAssessor } from './quality-assessor.js';
 import { OptimizationResult, OptimizationMode, OptimizationPhase, DocumentType, EscalationAnalysis, DepthLevel } from './types.js';
+import { EscalationThresholdsConfig } from '../../types/config.js';
 /**
  * v4.11: Extended context options for optimization modes
  */
@@ -16,7 +17,12 @@ export declare class UniversalOptimizer {
     private intentDetector;
     private patternLibrary;
     private qualityAssessor;
-    constructor(intentDetector?: IntentDetector, patternLibrary?: PatternLibrary, qualityAssessor?: QualityAssessor);
+    private thresholds;
+    constructor(intentDetector?: IntentDetector, patternLibrary?: PatternLibrary, qualityAssessor?: QualityAssessor, escalationConfig?: EscalationThresholdsConfig);
+    /**
+     * v4.12: Get current threshold configuration
+     */
+    getThresholds(): Required<EscalationThresholdsConfig>;
     /**
      * v4.11: Optimize a prompt using Clavix Intelligence
      * @param prompt The prompt to optimize
@@ -49,6 +55,7 @@ export declare class UniversalOptimizer {
     /**
      * v4.11: Analyze whether to escalate from standard to comprehensive depth
      * Uses multi-factor scoring for intelligent triage decisions
+     * v4.12: Uses configurable thresholds from EscalationThresholdsConfig
      *
      * IMPORTANT: Quality checks use the ORIGINAL prompt, not the enhanced one,
      * because triage decisions should be based on what the user wrote.

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

@@ -1,14 +1,34 @@
 import { IntentDetector } from './intent-detector.js';
 import { PatternLibrary } from './pattern-library.js';
 import { QualityAssessor } from './quality-assessor.js';
+/**
+ * v4.12: Default escalation thresholds
+ * These can be overridden via ClavixConfig.intelligence.escalation
+ */
+const DEFAULT_THRESHOLDS = {
+    comprehensiveAbove: 75,
+    standardFloor: 60,
+    intentConfidenceMin: 50,
+    strongRecommendAbove: 75,
+    suggestAbove: 45,
+};
 export class UniversalOptimizer {
     intentDetector;
     patternLibrary;
     qualityAssessor;
-    constructor(intentDetector, patternLibrary, qualityAssessor) {
+    thresholds;
+    constructor(intentDetector, patternLibrary, qualityAssessor, escalationConfig) {
         this.intentDetector = intentDetector || new IntentDetector();
         this.patternLibrary = patternLibrary || new PatternLibrary();
         this.qualityAssessor = qualityAssessor || new QualityAssessor();
+        // v4.12: Merge user config with defaults
+        this.thresholds = { ...DEFAULT_THRESHOLDS, ...escalationConfig };
+    }
+    /**
+     * v4.12: Get current threshold configuration
+     */
+    getThresholds() {
+        return { ...this.thresholds };
     }
     /**
      * v4.11: Optimize a prompt using Clavix Intelligence
@@ -143,6 +163,7 @@ export class UniversalOptimizer {
     /**
      * v4.11: Analyze whether to escalate from standard to comprehensive depth
      * Uses multi-factor scoring for intelligent triage decisions
+     * v4.12: Uses configurable thresholds from EscalationThresholdsConfig
      *
      * IMPORTANT: Quality checks use the ORIGINAL prompt, not the enhanced one,
      * because triage decisions should be based on what the user wrote.
@@ -150,6 +171,8 @@ export class UniversalOptimizer {
     analyzeEscalation(result) {
         const reasons = [];
         let totalScore = 0;
+        // v4.12: Use configurable thresholds
+        const { standardFloor, suggestAbove, strongRecommendAbove, intentConfidenceMin } = this.thresholds;
         // Assess the ORIGINAL prompt's quality for triage decisions
         // (result.quality is for the enhanced prompt)
         const originalQuality = this.qualityAssessor.assessQuality(result.original, result.intent.primaryIntent);
@@ -164,9 +187,10 @@ export class UniversalOptimizer {
                 description: `${result.intent.primaryIntent} tasks benefit from comprehensive analysis`,
             });
         }
-        // Factor 2: Low confidence (<60% → up to +20 pts)
-        if (result.intent.confidence < 60) {
-            const contribution = Math.round((60 - result.intent.confidence) / 3); // Max 20 pts
+        // Factor 2: Low confidence (< intentConfidenceMin+10 → up to +20 pts)
+        const confidenceThreshold = intentConfidenceMin + 10; // Default: 60
+        if (result.intent.confidence < confidenceThreshold) {
+            const contribution = Math.round((confidenceThreshold - result.intent.confidence) / 3); // Max 20 pts
             totalScore += contribution;
             reasons.push({
                 factor: 'low-confidence',
@@ -174,9 +198,10 @@ export class UniversalOptimizer {
                 description: `Intent detection confidence is low (${result.intent.confidence}%)`,
             });
         }
-        // Factor 3: Overall quality score (<65 → up to +25 pts) - uses ORIGINAL quality
-        if (originalQuality.overall < 65) {
-            const contribution = Math.round((65 - originalQuality.overall) / 2.6); // Max ~25 pts
+        // Factor 3: Overall quality score (< standardFloor+5 → up to +25 pts) - uses ORIGINAL quality
+        const qualityThreshold = standardFloor + 5; // Default: 65
+        if (originalQuality.overall < qualityThreshold) {
+            const contribution = Math.round((qualityThreshold - originalQuality.overall) / 2.6); // Max ~25 pts
             totalScore += contribution;
             reasons.push({
                 factor: 'low-quality',
@@ -184,8 +209,8 @@ export class UniversalOptimizer {
                 description: `Original prompt quality is below threshold (${Math.round(originalQuality.overall)}/100)`,
             });
         }
-        // Factor 4: Low completeness (<60% → +15 pts) - uses ORIGINAL quality
-        if (originalQuality.completeness < 60) {
+        // Factor 4: Low completeness (< standardFloor → +15 pts) - uses ORIGINAL quality
+        if (originalQuality.completeness < standardFloor) {
             const contribution = 15;
             totalScore += contribution;
             reasons.push({
@@ -194,8 +219,8 @@ export class UniversalOptimizer {
                 description: `Missing required details (completeness: ${Math.round(originalQuality.completeness)}%)`,
             });
         }
-        // Factor 5: Low specificity (<60% → +15 pts) - v4.0 new dimension, uses ORIGINAL quality
-        if (originalQuality.specificity < 60) {
+        // Factor 5: Low specificity (< standardFloor → +15 pts) - uses ORIGINAL quality
+        if (originalQuality.specificity < standardFloor) {
             const contribution = 15;
             totalScore += contribution;
             reasons.push({
@@ -215,7 +240,9 @@ export class UniversalOptimizer {
             });
         }
         // Factor 7: Length mismatch (short prompt + incomplete → +15 pts) - uses ORIGINAL quality
-        if (result.original.length < 50 && originalQuality.completeness < 70) {
+        const completenessLenientThreshold = standardFloor + 10; // Default: 70
+        if (result.original.length < 50 &&
+            originalQuality.completeness < completenessLenientThreshold) {
             const contribution = 15;
             totalScore += contribution;
             reasons.push({
@@ -235,13 +262,14 @@ export class UniversalOptimizer {
                 description: `${result.intent.primaryIntent} requires thorough analysis`,
             });
         }
-        // Determine escalation confidence
-        // Thresholds: 45 for escalation, 60 for medium confidence, 75 for high confidence
+        // v4.12: Determine escalation confidence using configurable thresholds
+        // suggestAbove for escalation, (suggestAbove+strongRecommendAbove)/2 for medium, strongRecommendAbove for high
+        const mediumThreshold = Math.round((suggestAbove + strongRecommendAbove) / 2); // Default: 60
         let escalationConfidence;
-        if (totalScore >= 75) {
+        if (totalScore >= strongRecommendAbove) {
             escalationConfidence = 'high';
         }
-        else if (totalScore >= 60) {
+        else if (totalScore >= mediumThreshold) {
             escalationConfidence = 'medium';
         }
         else {
@@ -250,8 +278,8 @@ export class UniversalOptimizer {
         // v4.11: Generate comprehensive mode value proposition
         const comprehensiveValue = this.generateComprehensiveValue(result, reasons);
         return {
-            // Threshold of 45 ensures planning prompts with missing completeness trigger escalation
-            shouldEscalate: totalScore >= 45,
+            // v4.12: Use configurable suggestAbove threshold (default: 45)
+            shouldEscalate: totalScore >= suggestAbove,
             escalationScore: Math.min(totalScore, 100),
             escalationConfidence,
             reasons,

package/dist/templates/agents/agents.md

@@ -9,7 +9,7 @@ This guide is for agents that can only read documentation (no slash-command supp
 **CRITICAL: Know which mode you're in and STOP at the right point.**
 
 **OPTIMIZATION workflows** (NO CODE ALLOWED):
-- Fast/deep optimization - Prompt improvement only
+- Improve mode - Prompt optimization only (auto-selects depth)
 - Your role: Analyze, optimize, show improved prompt, **STOP**
 - ❌ DO NOT implement the prompt's requirements
 - ✅ After showing optimized prompt, tell user: "Run `/clavix:execute --latest` to implement"
@@ -38,11 +38,11 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 |----------|-----------------|---------|
 | **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
 | **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
-| **Quick Optimization** | `workflows/fast.md` | Intent detection + quality assessment + smart triage |
-| **Deep Analysis** | `workflows/deep.md` | Comprehensive with alternatives, validation, edge cases |
+| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
 | **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
 | **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
 | **File Operations** | `core/file-operations.md` | File creation patterns |
+| **Verification** | `core/verification.md` | Post-implementation verification |
 
 **Troubleshooting:**
 - `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
@@ -55,11 +55,12 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 
 | Keywords in User Request | Recommended Workflow | File Reference |
 |---------------------------|---------------------|----------------|
-| "improve this prompt", "make it better", "optimize" | Fast mode → Quick optimization | `workflows/fast.md` |
-| "analyze thoroughly", "edge cases", "alternatives" | Deep mode → Comprehensive analysis | `workflows/deep.md` |
+| "improve this prompt", "make it better", "optimize" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
+| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.md` |
 | "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
 | "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
 | "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
+| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
 
 **When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
 
@@ -70,11 +71,14 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 | Command | Purpose |
 |---------|---------|
 | `clavix init` | Interactive setup with integration selection |
-| `clavix fast "<prompt>"` | Quick optimization (CLI auto-saves; agent must save manually per template instructions) |
-| `clavix deep "<prompt>"` | Deep analysis (CLI auto-saves; agent must save manually per template instructions) |
+| `clavix improve "<prompt>"` | Unified optimization with auto-depth selection |
+| `clavix improve --comprehensive "<prompt>"` | Force comprehensive analysis |
+| `clavix improve --standard "<prompt>"` | Force standard optimization |
+| `clavix analyze "<prompt>"` | JSON analysis output for programmatic use |
 | `clavix execute [--latest]` | Execute saved prompts (interactive or --latest) |
+| `clavix verify [--latest]` | Verify implementation against checklist |
 | `clavix prompts list` | View saved prompts with status (NEW, EXECUTED, OLD, STALE) |
-| `clavix prompts clear` | Manage cleanup (--executed, --stale, --fast, --deep, --all, --force) |
+| `clavix prompts clear` | Manage cleanup (--executed, --stale, --standard, --comprehensive, --all) |
 | `clavix prd` | Guided PRD generation → `full-prd.md` + `quick-prd.md` |
 | `clavix plan` | Transform PRD → phase-based `tasks.md` |
 | `clavix implement [--commit-strategy=<type>]` | Execute tasks (git strategies: per-task, per-5-tasks, per-phase, none) |
@@ -91,6 +95,8 @@ clavix init
 clavix version
 ```
 
+**Save behavior:** CLI auto-saves prompts to `.clavix/outputs/`. When using slash commands, the agent must save manually per template instructions (no automatic persistence).
+
 ---
 
 ## 🔄 Standard Workflow

package/dist/templates/agents/copilot-instructions.md

@@ -1,6 +1,6 @@
 # Clavix Instructions for GitHub Copilot
 
-These instructions enhance GitHub Copilot's understanding of Clavix Intelligence™ workflows available in this project.
+These instructions enhance GitHub Copilot's understanding of Clavix prompt optimization workflows available in this project.
 
 ---