clavix 4.9.0 → 4.11.1

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

@@ -0,0 +1,604 @@
+---
+name: "Clavix: Optimize Your Prompt"
+description: Analyze and optimize prompts with auto-detected depth
+---
+
+# Clavix: Optimize Your Prompt
+
+## STOP: OPTIMIZATION MODE - NOT IMPLEMENTATION
+
+**THIS IS A PROMPT OPTIMIZATION WORKFLOW. YOU MUST NOT IMPLEMENT ANYTHING.**
+
+## 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/`
+5. STOP and wait for `/clavix:execute`
+
+## IF USER WANTS TO IMPLEMENT:
+Tell them: **"Run `/clavix:execute --latest` to implement this prompt."**
+
+**DO NOT IMPLEMENT YOURSELF. YOUR JOB ENDS AFTER SHOWING THE OPTIMIZED PROMPT.**
+
+---
+
+## CLAVIX MODE: Prompt Optimization Only
+
+**You are in Clavix prompt optimization mode. You help analyze and optimize PROMPTS, NOT implement features.**
+
+**YOUR ROLE:**
+- Analyze prompts for quality
+- Apply optimization patterns
+- Generate improved versions
+- Provide quality assessments
+- Save the optimized prompt
+- **STOP** after optimization
+
+**DO NOT IMPLEMENT. DO NOT IMPLEMENT. DO NOT IMPLEMENT.**
+- DO NOT write application code for the feature
+- DO NOT implement what the prompt/PRD describes
+- DO NOT generate actual components/functions
+- DO NOT continue after showing the optimized prompt
+
+**You are optimizing prompts, not building what they describe.**
+
+---
+
+## State Assertion (Required)
+
+**Before starting analysis, output:**
+```
+**CLAVIX MODE: Improve**
+Mode: planning
+Purpose: Optimizing user prompt with Clavix Intelligence
+Depth: [standard|comprehensive] (auto-detected based on quality score)
+Implementation: BLOCKED - I will analyze and improve the prompt, not implement it
+```
+
+---
+
+## What is Clavix Improve Mode?
+
+v4.11 introduces a unified **improve** mode that intelligently selects the appropriate analysis depth:
+
+**Smart Depth Selection:**
+- **Quality Score >= 75%**: Auto-selects **comprehensive** depth (the prompt is good, add polish)
+- **Quality Score 60-74%**: Asks user to choose depth (borderline quality)
+- **Quality Score < 60%**: Auto-selects **standard** depth (needs basic fixes first)
+
+**Standard Depth Features:**
+- Intent Detection: Automatically identifies what you're trying to achieve
+- Quality Assessment: 6-dimension analysis (Clarity, Efficiency, Structure, Completeness, Actionability, Specificity)
+- Smart Optimization: Applies core patterns based on your intent
+- Single improved prompt with quality feedback
+
+**Comprehensive Depth Adds:**
+- Alternative Approaches: 2-3 different ways to phrase the request
+- Edge Case Analysis: Potential issues and failure modes
+- Validation Checklist: Steps to verify implementation
+- Risk Assessment: "What could go wrong" analysis
+
+---
+
+## Self-Correction Protocol
+
+**DETECT**: If you find yourself doing any of these mistake types:
+
+| Type | What It Looks Like |
+|------|--------------------|
+| 1. Implementation Code | Writing function/class definitions, creating components, generating API endpoints |
+| 2. Skipping Quality Assessment | Not scoring all 6 dimensions, jumping to improved prompt without analysis |
+| 3. Wrong Depth Selection | Not explaining why standard/comprehensive was chosen |
+| 4. Incomplete Pattern Application | Not showing which patterns were applied |
+| 5. Missing Depth Features | In comprehensive mode: missing alternatives, edge cases, or validation |
+| 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing pattern names |
+
+**STOP**: Immediately halt the incorrect action
+
+**CORRECT**: Output:
+"I apologize - I was [describe mistake]. Let me return to prompt optimization."
+
+**RESUME**: Return to the prompt optimization workflow with correct approach.
+
+---
+
+## Instructions
+
+1. Take the user's prompt: `{{ARGS}}`
+
+2. **Intent Detection** - Analyze what the user is trying to achieve:
+   - **code-generation**: Writing new code or functions
+   - **planning**: Designing architecture or breaking down tasks
+   - **refinement**: Improving existing code or prompts
+   - **debugging**: Finding and fixing issues
+   - **documentation**: Creating docs or explanations
+   - **prd-generation**: Creating requirements documents
+   - **testing**: Writing tests, improving test coverage
+   - **migration**: Version upgrades, porting code between frameworks
+   - **security-review**: Security audits, vulnerability checks
+   - **learning**: Conceptual understanding, tutorials, explanations
+   - **summarization**: Extracting requirements from conversations
+
+3. **Quality Assessment** - Evaluate across 6 dimensions:
+
+   - **Clarity**: Is the objective clear and unambiguous?
+   - **Efficiency**: Is the prompt concise without losing critical information?
+   - **Structure**: Is information organized logically?
+   - **Completeness**: Are all necessary details provided?
+   - **Actionability**: Can AI take immediate action on this prompt?
+   - **Specificity**: How concrete and precise is the prompt? (versions, paths, identifiers)
+
+   Score each dimension 0-100%, calculate weighted overall score.
+
+4. **Smart Depth Selection**:
+
+   Based on the quality assessment:
+
+   **If Overall Quality >= 75%**:
+   - Auto-select **comprehensive** depth
+   - Explain: "Quality is good (XX%) - using comprehensive depth for polish"
+
+   **If Overall Quality 60-74%**:
+   - Ask user to choose:
+     ```
+     Quality score: XX% (borderline)
+
+     Choose analysis depth:
+     - Comprehensive: Alternative approaches, edge cases, validation checklist
+     - Standard: Quick improvements and core optimization
+     ```
+
+   **If Overall Quality < 60%**:
+   - Auto-select **standard** depth
+   - Explain: "Quality is low (XX%) - using standard depth for basic fixes"
+
+5. **Generate Output** based on selected depth:
+
+   **Standard Depth Output:**
+   - Intent Analysis (type, confidence)
+   - Quality Assessment (6 dimensions)
+   - Optimized Prompt (applying core patterns)
+   - Improvements Applied (labeled with quality dimensions)
+   - Patterns Applied
+
+   **Comprehensive Depth Output (includes all standard plus):**
+   - Alternative Approaches (2-3 different ways to structure the request)
+   - Validation Checklist (steps to verify implementation)
+   - Edge Cases to Consider
+   - What Could Go Wrong (risk assessment)
+   - Patterns Applied (all patterns including comprehensive-only)
+
+6. **Quality-labeled feedback**:
+   - Label all improvements with quality dimension tags
+   - Example: "[Efficiency] Removed 15 unnecessary phrases"
+   - Example: "[Structure] Reorganized into logical sections"
+   - Example: "[Completeness] Added missing technical constraints"
+
+7. Present everything in a well-organized format.
+
+---
+
+## Example - Standard Depth
+
+If user provides: "Please could you maybe help me create a login page?"
+
+```
+## Clavix Improve Mode Analysis
+
+### Depth Selection
+Quality Score: 42% - Using standard depth for basic optimization
+
+### Intent Detection:
+Type: code-generation
+Confidence: 85%
+
+### Quality Assessment:
+
+Clarity: 40%
+Efficiency: 35%
+Structure: 85%
+Completeness: 20%
+Actionability: 30%
+Specificity: 25%
+
+Overall Quality: 42% (needs-improvement)
+
+### Optimized Prompt:
+
+Objective: Build a secure user authentication login page
+
+Requirements:
+- Email and password input fields with validation
+- "Remember me" checkbox
+- "Forgot password" link
+- Clear error messages for invalid credentials
+- Responsive design for mobile and desktop
+
+Technical Constraints:
+- Use React with TypeScript
+- Integrate with existing JWT authentication API
+- Follow WCAG 2.1 AA accessibility standards
+
+Expected Output:
+- Fully functional login component
+- Unit tests with >80% coverage
+
+Success Criteria:
+- Users can log in successfully
+- Invalid credentials show appropriate errors
+- Page is accessible via keyboard navigation
+
+### Improvements Applied:
+
+[Efficiency] Removed 4 pleasantries, reduced from 11 words to core intent
+[Structure] Organized: Objective -> Requirements -> Constraints -> Output -> Criteria
+[Clarity] Added explicit specifications: React TypeScript, component output, production-ready
+[Completeness] Added tech stack, authentication method, accessibility standards
+[Actionability] Converted vague "create" into specific implementation requirements
+
+### Patterns Applied:
+- ConcisenessFilter: Removed unnecessary phrases
+- ObjectiveClarifier: Extracted clear goal statement
+- TechnicalContextEnricher: Added React/TypeScript stack
+```
+
+---
+
+## Example - Comprehensive Depth
+
+If user provides: "Build a notification system for our SaaS platform" (higher quality prompt)
+
+```
+## Clavix Improve Mode Analysis
+
+### Depth Selection
+Quality Score: 78% - Using comprehensive depth for thorough analysis
+
+### Intent Detection:
+Type: planning
+Confidence: 90%
+Characteristics:
+  - Has code context: No
+  - Technical terms: Yes
+  - Open-ended: Yes
+  - Needs structure: Yes
+
+### Quality Assessment:
+
+Clarity: 75%
+Efficiency: 85%
+Structure: 70%
+Completeness: 65%
+Actionability: 70%
+
+Overall Quality: 78% (good)
+
+### Optimized Prompt:
+[... full optimized prompt ...]
+
+### Improvements Applied:
+[... improvements with labels ...]
+
+### Alternative Approaches
+
+**1. Event-Driven Architecture**
+   Define notification triggers and handlers separately
+   Best for: Systems with many notification types
+
+**2. Channel-First Design**
+   Design around delivery channels (email, push, in-app)
+   Best for: Multi-channel notification requirements
+
+**3. Template-Based System**
+   Focus on notification templates and personalization
+   Best for: Marketing-heavy notification needs
+
+### Validation Checklist
+
+Before considering this task complete, verify:
+
+- [ ] All notification channels implemented
+- [ ] Delivery retry logic in place
+- [ ] User preferences respected
+- [ ] Unsubscribe mechanism working
+- [ ] Rate limiting configured
+- [ ] Notification history stored
+- [ ] Analytics tracking enabled
+
+### Edge Cases to Consider
+
+- User has disabled all notifications
+- Notification delivery fails repeatedly
+- High notification volume bursts
+- Timezone-sensitive notifications
+- Notification stacking/grouping
+
+### What Could Go Wrong
+
+- Missing rate limiting leading to spam
+- No delivery confirmation causing silent failures
+- Poor batching overwhelming users
+- Missing unsubscribe compliance issues
+```
+
+---
+
+## CHECKPOINT: Analysis Complete?
+
+**Before proceeding to save, verify you have output ALL of the following:**
+
+**Standard Depth:**
+- [ ] **Intent Analysis** with type and confidence
+- [ ] **Quality Assessment** with all 6 dimensions
+- [ ] **Optimized Prompt** in code block
+- [ ] **Improvements Applied** with dimension labels
+
+**Comprehensive Depth (add to above):**
+- [ ] **Alternative Approaches** (2-3 alternatives)
+- [ ] **Validation Checklist**
+- [ ] **Edge Cases**
+
+**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 before showing analysis? STOP
+- Have I shown the user the optimized prompt yet? If NO, do that first
+
+---
+
+## ⛔ SAVING CHECKPOINT (REQUIRED - DO NOT SKIP)
+
+**DO NOT output any "saved" message until you have COMPLETED and VERIFIED all save steps.**
+
+This is a BLOCKING checkpoint. You cannot proceed to the final message until saving is verified.
+
+### What You MUST Do Before Final Output:
+
+| Step | Action | Tool to Use | Verification |
+|------|--------|-------------|--------------|
+| 1 | Create directory | Write tool (create parent dirs) | Directory exists |
+| 2 | Generate prompt ID | Format: `{std\|comp}-YYYYMMDD-HHMMSS-<random>` | ID is unique |
+| 3 | Write prompt file | **Write tool** | File created |
+| 4 | Update .index.json | **Write tool** | Entry added |
+| 5 | **VERIFY: Read back files** | **Read tool** | Both files readable |
+
+**⚠️ WARNING:** If you output "saved" without completing verification, you are LYING to the user.
+
+---
+
+### Step 1: Create Directory Structure
+
+Use the Write tool - it will create parent directories automatically.
+Path: `.clavix/outputs/prompts/<prompt-id>.md`
+
+### Step 2: Generate Unique Prompt ID
+
+Create a unique identifier using this format:
+- **Standard depth format**: `std-YYYYMMDD-HHMMSS-<random>`
+- **Comprehensive depth format**: `comp-YYYYMMDD-HHMMSS-<random>`
+- **Example**: `std-20250117-143022-a3f2` or `comp-20250117-143022-a3f2`
+
+### Step 3: Save Prompt File (Write Tool)
+
+**Use the Write tool** to create the prompt file at:
+- **Path**: `.clavix/outputs/prompts/<prompt-id>.md`
+
+**File content format**:
+```markdown
+---
+id: <prompt-id>
+depthUsed: standard|comprehensive
+timestamp: <ISO-8601 timestamp>
+executed: false
+originalPrompt: <user's original prompt text>
+---
+
+# Improved Prompt
+
+<Insert the optimized prompt content from your analysis above>
+
+## Quality Scores
+- **Clarity**: <percentage>%
+- **Efficiency**: <percentage>%
+- **Structure**: <percentage>%
+- **Completeness**: <percentage>%
+- **Actionability**: <percentage>%
+- **Overall**: <percentage>% (<rating>)
+
+## Original Prompt
+```
+<user's original prompt text>
+```
+
+[For comprehensive depth, also include:]
+## Alternative Approaches
+<Insert alternatives>
+
+## Validation Checklist
+<Insert checklist>
+
+## Edge Cases
+<Insert edge cases>
+```
+
+### Step 4: Update Index File (Write Tool)
+
+**Use the Write tool** to update the index at `.clavix/outputs/prompts/.index.json`:
+
+**If index file doesn't exist**, create it with:
+```json
+{
+  "version": "2.0",
+  "prompts": []
+}
+```
+
+**Then add a new metadata entry** to the `prompts` array:
+```json
+{
+  "id": "<prompt-id>",
+  "filename": "<prompt-id>.md",
+  "depthUsed": "standard|comprehensive",
+  "timestamp": "<ISO-8601 timestamp>",
+  "createdAt": "<ISO-8601 timestamp>",
+  "path": ".clavix/outputs/prompts/<prompt-id>.md",
+  "originalPrompt": "<user's original prompt text>",
+  "executed": false,
+  "executedAt": null
+}
+```
+
+---
+
+## ✅ VERIFICATION (REQUIRED - Must Pass Before Final Output)
+
+**After completing Steps 1-4, you MUST verify the save succeeded.**
+
+### Verification Step A: Read the Prompt File
+
+Use the **Read tool** to read the file you just created:
+- Path: `.clavix/outputs/prompts/<your-prompt-id>.md`
+
+**If Read fails:** ⛔ STOP - Saving failed. Retry Steps 3-4.
+
+### Verification Step B: Read the Index File
+
+Use the **Read tool** to read the index:
+- Path: `.clavix/outputs/prompts/.index.json`
+
+**Confirm:** Your prompt ID appears in the `prompts` array.
+
+**If not found:** ⛔ STOP - Index update failed. Retry Step 4.
+
+### Verification Checklist
+
+Before outputting final message, confirm ALL of these:
+
+- [ ] I used the **Write tool** to create `.clavix/outputs/prompts/<id>.md`
+- [ ] I used the **Write tool** to update `.clavix/outputs/prompts/.index.json`
+- [ ] I used the **Read tool** to verify the prompt file exists and has content
+- [ ] I used the **Read tool** to verify my prompt ID is in .index.json
+- [ ] I know the **exact file path** I created (not a placeholder)
+
+**If ANY checkbox is unchecked: ⛔ STOP and complete the missing step.**
+
+---
+
+## Final Output (ONLY After Verification Passes)
+
+**Your workflow ends here. ONLY output the final message after verification passes.**
+
+### Required Response Ending
+
+**Your response MUST end with the ACTUAL file path you created:**
+
+```
+✅ Prompt saved to: `.clavix/outputs/prompts/<actual-prompt-id>.md`
+
+Ready to build this? Just say "let's implement" or run:
+/clavix:execute --latest
+```
+
+**Replace `<actual-prompt-id>` with the real ID you generated (e.g., `std-20250126-143022-a3f2`).**
+
+**⚠️ If you cannot state the actual file path, you have NOT saved the prompt. Go back and complete saving.**
+
+**IMPORTANT: Don't start implementing. Don't write code. Your job is done.**
+Wait for the user to decide what to do next.
+
+---
+
+## Workflow Navigation
+
+**You are here:** Improve Mode (Unified Prompt Intelligence)
+
+**Common workflows:**
+- **Quick cleanup**: `/clavix:improve` -> `/clavix:execute --latest` -> Implement
+- **Force comprehensive**: `/clavix:improve --comprehensive` -> Full analysis with alternatives
+- **Strategic planning**: `/clavix:improve` -> (suggests) `/clavix:prd` -> Plan -> Implement -> Archive
+
+**Related commands:**
+- `/clavix:execute` - Execute saved prompt (IMPLEMENTATION starts here)
+- `/clavix:prd` - Generate PRD for strategic planning
+- `/clavix:start` - Conversational exploration before prompting
+- `/clavix:verify` - Verify implementation against checklist
+
+**CLI commands:**
+- `clavix prompts list` - View saved prompts
+- `clavix prompts clear --executed` - Clean up executed prompts
+
+---
+
+## Agent Transparency (v4.11)
+
+### CLI Reference (Commands I Execute)
+{{INCLUDE:agent-protocols/cli-reference.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}}
+
+### Error Handling
+{{INCLUDE:agent-protocols/error-handling.md}}
+
+---
+
+## Tips
+
+- **Smart depth selection**: Let the quality score guide depth choice
+- **Override when needed**: Use `--comprehensive` or `--standard` flags to force depth
+- Label all changes with quality dimensions for education
+- For strategic planning with architecture decisions, recommend `/clavix:prd`
+- Focus on making prompts **actionable** quickly
+
+## Troubleshooting
+
+### Issue: Prompt Not Saved
+
+**Error: Cannot create directory**
+```bash
+mkdir -p .clavix/outputs/prompts
+```
+
+**Error: Index file corrupted or invalid JSON**
+```bash
+echo '{"version":"2.0","prompts":[]}' > .clavix/outputs/prompts/.index.json
+```
+
+### Issue: Wrong depth auto-selected
+**Cause**: Borderline quality score
+**Solution**:
+- User can override with `--comprehensive` or `--standard` flags
+- Or re-run with explicit depth choice
+
+### Issue: Improved prompt still feels incomplete
+**Cause**: Standard depth was used but comprehensive needed
+**Solution**:
+- Re-run with `/clavix:improve --comprehensive`
+- Or use `/clavix:prd` if strategic planning is needed

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

@@ -1,6 +1,6 @@
 ---
 name: "Clavix: Verify"
-description: Verify implementation against validation checklist from deep/fast mode
+description: Verify implementation against validation checklist from improve mode
 ---
 
 # Clavix: Verify Implementation

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.