clavix 4.8.1 → 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/archive.md

@@ -3,47 +3,69 @@ name: "Clavix: Archive"
 description: Archive completed PRD projects
 ---
 
-# Clavix Archive - PRD Project Archival
+# Clavix: Archive Your Completed Work
 
-> **⚠️ Agent Execution Note**: This command requires CLI execution. AI agents should run `clavix archive` via Bash tool to perform archival operations. Direct file manipulation is not recommended due to state tracking complexity.
+Done with a project? I'll move it to the archive to keep your workspace tidy. You can always restore it later if needed.
 
-You are helping the user archive completed PRD projects to keep their workspace organized.
+---
 
-## Instructions
+## What This Does
 
-### Part A: Agent Execution Protocol
+When you run `/clavix:archive`, I:
+1. **Find your completed projects** - Look for 100% done PRDs
+2. **Ask which to archive** - You pick, or I archive all completed ones
+3. **Move to archive folder** - Out of the way but not deleted
+4. **Track everything** - So you can restore later if needed
 
-**As an AI agent, you should:**
+**Your work is never deleted, just organized.**
 
-1. **Run the CLI command** to handle archival operations:
-   ```bash
-   clavix archive
-   ```
+---
+
+## CLAVIX MODE: Archival
+
+**I'm in archival mode. Organizing your completed work.**
+
+**What I'll do:**
+- ✓ Find projects ready for archive
+- ✓ Show you what's complete (100% tasks done)
+- ✓ Move projects to archive when you confirm
+- ✓ Track everything so you can restore later
+
+**What I won't do:**
+- ✗ Delete anything without explicit confirmation
+- ✗ Archive projects you're still working on (unless you use --force)
+- ✗ Make decisions for you - you pick what to archive
+
+---
+
+## How I Archive Projects
+
+**I handle all the commands - you just tell me what to do.**
 
-   The CLI will:
-   - Prompt user for project selection
-   - Validate task completion status
-   - Handle file operations safely
-   - Update state tracking
+### What I Run (You Don't Need To)
 
-2. **Choose the appropriate mode** based on user intent:
+| What You Want | Command I Execute |
+|---------------|-------------------|
+| Archive completed project | `clavix archive` |
+| Archive specific project | `clavix archive [name]` |
+| Archive incomplete work | `clavix archive [name] --force` |
+| Delete permanently | `clavix archive [name] --delete` |
+| See what's archived | `clavix archive --list` |
+| Restore from archive | `clavix archive --restore [name]` |
 
-   - **Interactive mode** (no arguments): User selects from list
-   - **Specific project**: `clavix archive [project-name]`
-   - **Force archive incomplete**: `clavix archive [project-name] --force`
-   - **Permanent delete**: `clavix archive [project-name] --delete`
-   - **List archived**: `clavix archive --list`
-   - **Restore**: `clavix archive --restore [project-name]`
+### Before I Archive
 
-3. **Before running the command**, validate:
-   - Check if `.clavix/outputs/` directory exists
-   - Verify user intent (archive vs delete vs restore)
-   - Confirm project name if specified
+I check:
+- ✓ Projects exist in `.clavix/outputs/`
+- ✓ What you want to do (archive, delete, restore)
+- ✓ Project name is correct
 
-4. **After CLI completes**, communicate results:
-   - Confirm where project was moved
-   - Mention restoration is possible (unless deleted)
-   - Update user on next steps
+### After Archiving
+
+I tell you:
+- Where the project went
+- How to restore it (unless you deleted it)
+- What to do next
 
 ### Part B: Understanding Archive Operations
 
@@ -238,57 +260,21 @@ User types: api-experiment-1
 Result: Project permanently deleted from .clavix/outputs/api-experiment-1/
 ```
 
-## AI Agent Guidelines
-
-When user mentions archiving or cleaning up projects:
-
-1. **Validate prerequisites before running CLI**:
-   - Check if `.clavix/outputs/` directory exists
-   - If not, inform user no projects exist to archive
-   - Verify user intent (list, archive, restore, delete)
-
-2. **Check completion status first**:
-   - Run `clavix archive` (interactive mode) to see archivable projects
-   - CLI will display projects with completion percentages
-   - Review output and communicate options to user
-
-3. **Execute the appropriate command**:
-   - **Interactive selection**: `clavix archive` (let user pick from list)
-   - **Specific project**: `clavix archive [project-name]`
-   - **Force incomplete**: `clavix archive [project-name] --force`
-   - **List archived**: `clavix archive --list`
-   - **Restore**: `clavix archive --restore [project-name]`
-   - **Delete**: `clavix archive [project-name] --delete` (with extra caution)
-
-4. **Confirm before archiving**:
-   - If using specific project mode, confirm project name with user
-   - Mention the archive location (`.clavix/outputs/archive/`)
-   - Explain that restoration is possible
-
-5. **Use --force cautiously**:
-   - Only when user explicitly wants to archive incomplete work
-   - Run command and let CLI show incomplete task count
-   - CLI will ask for user confirmation
-   - Explain they won't lose data (just moving location)
-
-6. **Suggest restoration when appropriate**:
-   - If user mentions old/past work, check archive first
-   - Run `clavix archive --list` to show what's archived
-   - Offer to restore if needed via `clavix archive --restore [project]`
-
-7. **Handle delete requests with extreme caution**:
-   - Always ask: "Do you want to DELETE (permanent) or ARCHIVE (safe)?"
-   - Explain that delete is permanent and irreversible
-   - Suggest archive as the safer default
-   - Use decision tree to help user decide
-   - Only run `--delete` after clear confirmation from user
-   - Double-check it's truly no-value content (failed experiments, duplicates, test data)
-   - CLI will require typing project name to confirm - this is expected
-
-8. **After CLI execution**:
-   - Communicate success/failure clearly
-   - Mention next steps (e.g., "Project archived, you can restore with `/clavix:archive --restore`")
-   - If error occurs, explain and suggest recovery options
+---
+
+## Agent Transparency (v4.9)
+
+### CLI Reference (Commands I Execute)
+{{INCLUDE:agent-protocols/cli-reference.md}}
+
+### Error Handling
+{{INCLUDE:agent-protocols/error-handling.md}}
+
+### Recovery Patterns
+{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
+
+### Agent Decision Rules
+{{INCLUDE:agent-protocols/decision-rules.md}}
 
 ## Workflow Navigation
 

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."**
@@ -207,30 +214,35 @@ Deep mode provides **Clavix Intelligence™** with comprehensive analysis that g
 
 ---
 
-## Agent Transparency (v4.6)
+## Agent Transparency (v4.9)
 
-### Quality Output Format
-{{INCLUDE:agent-protocols/quality-output.md}}
+### How to Explain Improvements
+{{INCLUDE:sections/improvement-explanations.md}}
+
+### Quality Dimensions (Plain English)
+{{INCLUDE:references/quality-dimensions.md}}
+
+### When to Recommend PRD Mode
+{{INCLUDE:sections/escalation-factors.md}}
+
+### What Made the Biggest Difference
+{{INCLUDE:sections/pattern-impact.md}}
 
 ### Agent Decision Rules
 {{INCLUDE:agent-protocols/decision-rules.md}}
 
-### Assertion Checkpoints
-{{INCLUDE:agent-protocols/assertion-checkpoints.md}}
-
-### Patterns Applied
-{{INCLUDE:sections/pattern-visibility.md}}
+### Error Handling
+{{INCLUDE:agent-protocols/error-handling.md}}
 
 ### Deep Mode Pattern Selection
-Deep mode has access to all patterns including deep-exclusive patterns:
-- **AlternativePhrasingGenerator**: Generates 2-3 alternative prompt structures
-- **EdgeCaseIdentifier**: Identifies domain-specific edge cases
-- **ValidationChecklistCreator**: Creates implementation verification checklist
-- **AssumptionExplicitizer**: Makes implicit assumptions explicit
-- **ScopeDefiner**: Adds explicit scope boundaries
-- **PRDStructureEnforcer**: Ensures PRD completeness (PRD mode only)
-- **ErrorToleranceEnhancer**: Adds error handling requirements
-- **PrerequisiteIdentifier**: Identifies prerequisites and dependencies
+Deep mode has access to all patterns including comprehensive analysis:
+- **Alternative Approaches**: 2-3 different ways to structure the request
+- **Edge Cases**: Things that might go wrong or need special handling
+- **Validation Checklist**: Steps to verify the implementation is complete
+- **Hidden Assumptions**: Things you might be assuming but didn't say
+- **Scope Boundaries**: What's in and out of scope
+- **Error Handling**: How to deal with failures gracefully
+- **Prerequisites**: What needs to exist before starting
 
 ---
 
@@ -376,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)
@@ -479,27 +519,26 @@ Confirm:
 - Index file updated with new entry
 - Display success message: `✓ Prompt saved: <prompt-id>.md`
 
-### Executing the Saved Prompt
-
-After saving completes successfully:
+### After Saving
 
 ---
 
 ## ⛔ STOP HERE - Agent Verification Required
 
-**Your workflow ends here. Before responding to the user:**
+**Your workflow ends here. After saving the prompt, verify it worked.**
 
 ### CLI Verification (Run This Command)
+I run this command to confirm the save worked:
 ```bash
 clavix prompts list
 ```
 
-**Verify**: Your prompt appears in the list with status "pending" or "NEW".
+**If it worked**: Your prompt appears in the list.
 
-**If verification fails**:
-- Check if file was saved to `.clavix/outputs/prompts/deep/`
-- Retry the save operation
-- Check file permissions
+**If it failed**:
+- I create the directory: `mkdir -p .clavix/outputs/prompts/deep`
+- I try saving again
+- If still failing, I tell you: "I had trouble saving, but here's your improved prompt..."
 
 ### Required Response Ending
 
@@ -507,26 +546,28 @@ clavix prompts list
 ```
 ✅ Deep analysis complete. Prompt optimized and saved.
 
-To implement this prompt, run:
+Ready to build this? Just say "let's implement" or run:
 /clavix:execute --latest
 ```
 
-**DO NOT continue to implementation. DO NOT write any code. STOP HERE.**
+**IMPORTANT: I don't start implementing. I don't write code. My job is done.**
+I wait for you to decide what to do next.
 
 ---
 
-### Prompt Management (CLI Commands)
+### Prompt Management (Commands I Run)
+
+These are commands I execute when needed - you don't need to run them.
 
-**List all saved prompts:**
+**Check saved prompts:**
 ```bash
 clavix prompts list
 ```
 
-**Cleanup after execution:**
+**Cleanup (I run when you ask or during maintenance):**
 ```bash
-clavix prompts clear --executed  # Remove executed prompts
-clavix prompts clear --stale     # Remove >30 day old prompts
-clavix prompts clear --deep      # Remove all deep prompts
+clavix prompts clear --executed  # Remove implemented prompts
+clavix prompts clear --stale     # Remove old prompts (>30 days)
 ```
 
 ## Workflow Navigation