clavix 4.9.0 → 4.10.0

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

@@ -0,0 +1,14 @@
+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>;
+    private calculateEscalation;
+}
+//# sourceMappingURL=analyze.d.ts.map

package/dist/cli/commands/analyze.js

@@ -0,0 +1,127 @@
+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();
+        const result = await optimizer.optimize(args.prompt, 'fast');
+        // 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));
+    }
+    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');
+        }
+        // Determine recommendation based on score and intent
+        let recommend = 'fast';
+        if (result.intent.primaryIntent === 'prd-generation') {
+            recommend = 'prd';
+        }
+        else if (score >= 60 || result.quality.overall < 50) {
+            recommend = 'deep';
+        }
+        else if (score >= 35) {
+            recommend = 'deep';
+        }
+        // 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,
+            factors,
+        };
+    }
+}
+//# sourceMappingURL=analyze.js.map

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

@@ -7,19 +7,26 @@ description: Comprehensive analysis with alternatives, edge cases, and validatio
 
 **THIS IS A PROMPT ANALYSIS WORKFLOW. YOU MUST NOT IMPLEMENT ANYTHING.**
 
-## YOU MUST NOT:
-- ❌ Write any application code
-- ❌ Create any new files (except prompt save files)
-- ❌ Modify any existing project code
-- ❌ Start implementing the prompt's requirements
-- ❌ Generate components, functions, or features
-
-## YOU MUST:
-1. ✅ Analyze the user's prompt comprehensively
-2. ✅ Apply all intelligence patterns
-3. ✅ Show the optimized prompt + alternatives + edge cases
-4. ✅ Save the prompt (CLI command or manual)
-5. ✅ **STOP and wait** for user to run `/clavix:execute`
+## Critical Understanding
+
+This template exists because agents (including you) tend to "help" by doing work immediately.
+**That's the wrong behavior here.** Your job is to ANALYZE and IMPROVE the prompt, then STOP.
+
+## What "Implementation" Looks Like (ALL FORBIDDEN)
+- ❌ Reading project files to "understand context" before showing analysis
+- ❌ Writing any code files (functions, classes, components)
+- ❌ Creating components, features, or API endpoints
+- ❌ Running build/test commands on the user's project
+- ❌ Making git commits
+- ❌ ANY action that modifies files outside `.clavix/`
+- ❌ Exploring the codebase before outputting your analysis
+
+## The ONLY Actions Allowed
+1. ✅ Read the user's prompt text (the `{{ARGS}}` provided)
+2. ✅ Analyze it comprehensively using the workflow below
+3. ✅ Output the analysis (intent, quality, optimized prompt, alternatives, edge cases)
+4. ✅ Save to `.clavix/outputs/prompts/deep/`
+5. ✅ STOP and wait for `/clavix:execute`
 
 ## IF USER WANTS TO IMPLEMENT:
 Tell them: **"Run `/clavix:execute --latest` to implement this prompt."**
@@ -381,6 +388,34 @@ Consider using `/clavix:prd` if this login page is part of a larger authenticati
 - **Deep mode** (`/clavix:deep`): Comprehensive analysis - best for complex prompts needing exploration
 - **PRD mode** (`/clavix:prd`): Strategic planning - best for features requiring architecture/business decisions
 
+---
+
+## ⛔ CHECKPOINT: Analysis Complete?
+
+**Before proceeding to save, verify you have output ALL of the following:**
+
+- [ ] **Intent Analysis** section with type and confidence %
+- [ ] **Quality Assessment** with all 6 dimensions scored
+- [ ] **Optimized Prompt** in a code block
+- [ ] **Improvements Applied** list with dimension labels
+- [ ] **Alternative Approaches** (2-3 alternatives)
+- [ ] **Validation Checklist** for implementation verification
+- [ ] **Edge Cases** to consider
+
+**If ANY checkbox above is unchecked, STOP. Go back and complete the analysis.**
+
+**Self-Check Before Any Action:**
+- Am I about to write/edit code files? → STOP (only `.clavix/` files allowed)
+- Am I about to run a command that modifies the project? → STOP
+- Am I exploring the codebase to "understand" before showing analysis? → STOP
+- Have I shown the user the optimized prompt yet? → If NO, do that first
+
+If any tripwire triggered: Output "I was about to [action]. Let me return to deep prompt analysis."
+
+Only after ALL items are checked should you proceed to the "Saving the Prompt" section below.
+
+---
+
 ## Next Steps
 
 ### Saving the Prompt (REQUIRED)

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

@@ -213,6 +213,19 @@ After I finish implementing and verification passes:
 
 ---
 
+## Finding Your Way Around
+
+Need to see what projects exist or check progress? I use these commands:
+
+| What I Need | Command I Run |
+|-------------|---------------|
+| See all projects | `clavix list` |
+| Check a specific project | `clavix show --output <project>` |
+| See active sessions | `clavix list --sessions` |
+| Find archived work | `clavix list --archived` |
+
+---
+
 ## When Things Go Wrong
 
 ### No Prompts Found

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

@@ -7,19 +7,26 @@ description: Quick prompt improvements with smart quality assessment and triage
 
 **THIS IS A PROMPT OPTIMIZATION WORKFLOW. YOU MUST NOT IMPLEMENT ANYTHING.**
 
-## YOU MUST NOT:
-- ❌ Write any application code
-- ❌ Create any new files (except prompt save files)
-- ❌ Modify any existing project code
-- ❌ Start implementing the prompt's requirements
-- ❌ Generate components, functions, or features
-
-## YOU MUST:
-1. ✅ Analyze the user's prompt
-2. ✅ Apply intelligence patterns
-3. ✅ Show the optimized prompt
-4. ✅ Save the prompt (CLI command or manual)
-5. ✅ **STOP and wait** for user to run `/clavix:execute`
+## Critical Understanding
+
+This template exists because agents (including you) tend to "help" by doing work immediately.
+**That's the wrong behavior here.** Your job is to ANALYZE and IMPROVE the prompt, then STOP.
+
+## What "Implementation" Looks Like (ALL FORBIDDEN)
+- ❌ Reading project files to "understand context" before showing analysis
+- ❌ Writing any code files (functions, classes, components)
+- ❌ Creating components, features, or API endpoints
+- ❌ Running build/test commands on the user's project
+- ❌ Making git commits
+- ❌ ANY action that modifies files outside `.clavix/`
+- ❌ Exploring the codebase before outputting your analysis
+
+## The ONLY Actions Allowed
+1. ✅ Read the user's prompt text (the `{{ARGS}}` provided)
+2. ✅ Analyze it using the workflow below
+3. ✅ Output the analysis (intent, quality, optimized prompt)
+4. ✅ Save to `.clavix/outputs/prompts/fast/`
+5. ✅ STOP and wait for `/clavix:execute`
 
 ## IF USER WANTS TO IMPLEMENT:
 Tell them: **"Run `/clavix:execute --latest` to implement this prompt."**
@@ -290,6 +297,31 @@ Success Criteria:
 [Actionability] Converted vague "create" into specific implementation requirements with measurable success criteria
 ```
 
+---
+
+## ⛔ CHECKPOINT: Analysis Complete?
+
+**Before proceeding to save, verify you have output ALL of the following:**
+
+- [ ] **Intent Analysis** section with type and confidence %
+- [ ] **Quality Assessment** with all 6 dimensions scored
+- [ ] **Optimized Prompt** in a code block
+- [ ] **Improvements Applied** list with dimension labels
+
+**If ANY checkbox above is unchecked, STOP. Go back and complete the analysis.**
+
+**Self-Check Before Any Action:**
+- Am I about to write/edit code files? → STOP (only `.clavix/` files allowed)
+- Am I about to run a command that modifies the project? → STOP
+- Am I exploring the codebase to "understand" before showing analysis? → STOP
+- Have I shown the user the optimized prompt yet? → If NO, do that first
+
+If any tripwire triggered: Output "I was about to [action]. Let me return to prompt optimization."
+
+Only after ALL items are checked should you proceed to the "Saving the Prompt" section below.
+
+---
+
 ## Next Steps
 
 ### Saving the Prompt (REQUIRED)

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

@@ -94,6 +94,23 @@ Me:     "All tasks complete! Your project is built."
 No problem! Just run `/clavix:implement` again and I pick up where we left off.
 The checkboxes in tasks.md track exactly what's done.
 
+## ⚠️ Critical Command: task-complete
+
+**After finishing EACH task, I MUST run:**
+```bash
+clavix task-complete <task-id>
+```
+
+**Why this matters:**
+- Updates tasks.md automatically (checkboxes)
+- Tracks progress correctly in config
+- Triggers git commits (if enabled)
+- Shows me the next task
+
+**NEVER manually edit tasks.md checkboxes** - always use this command.
+
+---
+
 ## How I Mark Tasks Complete
 
 **I handle this automatically - you don't need to do anything.**
@@ -141,6 +158,17 @@ Starting now...
 - Guess what you want - I'll ask instead
 - Edit checkboxes manually (I use the command)
 
+## Finding Your Way Around
+
+Need to see what projects exist or check progress? I use these commands:
+
+| What I Need | Command I Run |
+|-------------|---------------|
+| See all projects | `clavix list` |
+| Check a specific project | `clavix show --output <project>` |
+| See active sessions | `clavix list --sessions` |
+| Find archived work | `clavix list --archived` |
+
 ## When I Can't Continue (Blocked Tasks)
 
 Sometimes I hit a wall. Here's what happens:

package/dist/templates/slash-commands/_components/agent-protocols/cli-reference.md

@@ -24,6 +24,18 @@ clavix fast "build a todo app"
 clavix deep "create authentication system with OAuth"
 ```
 
+#### `clavix analyze "prompt"`
+**What it does:** Returns structured JSON with intent, quality scores, and escalation recommendation
+**When to run:** When you need data-driven decision on which mode to use
+**You say:** Nothing - this is for internal decision-making
+**Example:**
+```bash
+clavix analyze "build a login page"
+```
+**Output:** JSON with `intent`, `confidence`, `quality` (6 dimensions), `escalation` (score + recommendation)
+**Flags:**
+- `--pretty` - Pretty-print the JSON output
+
 #### `clavix prompts list`
 **What it does:** Shows all saved prompts with their status
 **When to run:** To verify a prompt was saved, or find prompt IDs

package/dist/templates/slash-commands/_components/agent-protocols/self-correction.md

@@ -9,6 +9,8 @@
 - Writing test files for the user's feature
 - Creating database schemas/migrations
 - Writing configuration files for deployment
+- **Reading project files to "understand context" before showing analysis**
+- **Exploring the codebase before outputting optimized prompt**
 
 ### Mistake Type 2: Skipping Quality Assessment
 - Not scoring all 6 quality dimensions
@@ -37,6 +39,23 @@
 
 **STOP**: Immediately halt the incorrect action
 
-**CORRECT**: Output an acknowledgment and return to correct workflow
+**CORRECT**: Output an acknowledgment:
+> "I was about to [describe action]. Let me return to [fast/deep] prompt analysis."
 
 **RESUME**: Return to the appropriate Clavix workflow for this mode
+
+---
+
+## Anti-Implementation Tripwires
+
+**Before your next tool call or action, check:**
+
+| Action | Tripwire | Response |
+|--------|----------|----------|
+| About to read project files | STOP | "I don't need to explore the codebase for prompt optimization" |
+| About to write code files | STOP | "Only `.clavix/` files are allowed in optimization mode" |
+| About to run build/test commands | STOP | "Project commands are for `/clavix:execute`, not optimization" |
+| About to make git commits | STOP | "Git operations belong in implementation mode" |
+| Haven't shown optimized prompt yet | STOP | "I need to show the analysis first" |
+
+**If any tripwire triggers:** Output the response and return to prompt analysis.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "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.",
   "type": "module",
   "main": "dist/index.js",