clavix 4.8.1 → 4.10.0

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

@@ -5,239 +5,284 @@ description: Execute saved prompts from fast/deep optimization
 
 # Clavix: Execute Saved Prompts
 
-Implement optimized prompts from `/clavix:fast` or `/clavix:deep`.
+Time to build! You've optimized a prompt with `/clavix:fast` or `/clavix:deep` - now I'll implement it.
 
-Prompts are automatically saved to `.clavix/outputs/prompts/fast/` or `.clavix/outputs/prompts/deep/`.
+Your saved prompts live in `.clavix/outputs/prompts/fast/` or `.clavix/outputs/prompts/deep/`.
+
+---
+
+## What This Does
+
+When you run `/clavix:execute`, I:
+1. **Find your prompt** - Load what you saved from fast/deep mode
+2. **Understand what to build** - Read the requirements and checklist
+3. **Implement everything** - Write the code, create files, build features
+4. **Run verification automatically** - Make sure everything works
+5. **Clean up when done** - Remove executed prompts
+
+**I do ALL of this automatically. You just watch (or grab coffee).**
 
 ---
 
 ## CLAVIX MODE: Implementation
 
-**You are in Clavix implementation mode. You ARE authorized to write code and implement features.**
+**I'm in implementation mode. Building time!**
 
-**YOUR ROLE:**
-- ✓ Read and understand prompt requirements
-- ✓ Implement the optimized prompt
+**What I'll do:**
+- ✓ Read and understand your prompt requirements
+- ✓ Implement everything in the optimized prompt
 - ✓ Write production-quality code
-- ✓ Follow prompt specifications
-- ✓ Execute saved prompts from fast/deep modes
+- ✓ Follow the specifications exactly
+- ✓ Run tests and verification automatically
+- ✓ Handle errors and fix issues
 
-**IMPLEMENTATION AUTHORIZED:**
-- ✓ Writing functions, classes, and components
-- ✓ Creating new files and modifying existing ones
-- ✓ Implementing features described in saved prompts
-- ✓ Writing tests for implemented code
+**What I'm authorized to create:**
+- ✓ Functions, classes, and components
+- ✓ New files and file modifications
+- ✓ Tests for implemented code
+- ✓ Configuration files if needed
 
-**MODE ENTRY VALIDATION:**
-Before implementing, verify:
-1. Source documents exist (prompts in .clavix/outputs/prompts/)
-2. Output assertion: "Entering IMPLEMENTATION mode. I will implement the saved prompt."
+**Before I start, I'll confirm:**
+> "Starting implementation mode. Building your [feature description]..."
 
 For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
 
 ---
 
-## Prerequisites
+## Before You Start
 
-Save a prompt first:
-```bash
-/clavix:fast "your prompt"
-# or
-/clavix:deep "your prompt"
-```
+You need a saved prompt first. Run one of these:
+- `/clavix:fast "your prompt"` - Quick improvements
+- `/clavix:deep "your prompt"` - Comprehensive analysis
 
-## Usage
+Then come back here with `/clavix:execute`.
 
-**Execute latest prompt (recommended):**
-```bash
-clavix execute --latest
-```
+---
 
-**Execute latest fast/deep:**
-```bash
-clavix execute --latest --fast
-clavix execute --latest --deep
-```
+## How I Execute Your Prompt
 
-**Interactive selection:**
-```bash
-clavix execute
-```
+### The Quick Version
 
-**Execute specific prompt:**
-```bash
-clavix execute --id <prompt-id>
+```
+You:    /clavix:execute
+Me:     [Finds your latest prompt]
+        [Reads requirements]
+        [Implements everything]
+        [Runs verification]
+Me:     "Done! Here's what I built..."
 ```
 
-## Agent Workflow
+### The Detailed Version
 
-1. Run `clavix execute --latest`
-2. Read displayed prompt content
-3. Implement requirements
-4. **REQUIRED: Run verification**: `clavix verify --latest`
-5. After verification passes, cleanup: `clavix prompts clear --executed`
+**Step 1: I find your prompt**
 
----
+I automatically run these commands (you don't need to):
+- `clavix execute --latest` - Get most recent prompt
+- Or `clavix execute --latest --fast` - Get latest fast mode prompt
+- Or `clavix execute --id <id>` - Get specific prompt
 
-## ⚠️ REQUIRED: Post-Implementation Verification
+**Step 2: I read and understand**
 
-**Verification is a REQUIRED step after implementation.**
+I'll parse the prompt file, extract:
+- The objective (what to build)
+- Requirements (specifics to implement)
+- Technical constraints (how to build it)
+- Success criteria (how to know it's done)
 
-After implementing the prompt requirements, you MUST verify your implementation against the checklist:
+**Step 3: I implement everything**
 
-```bash
-clavix verify --latest
-```
+This is where I actually write code:
+- Create new files as needed
+- Modify existing files
+- Write functions, components, classes
+- Add tests if specified
 
-### What Verification Does
+**Step 4: I verify automatically**
 
-1. **Loads the checklist** from your executed prompt (validation items, edge cases, risks)
-2. **Runs automated hooks** (test, build, lint) for items that can be verified programmatically
-3. **Guides manual verification** for items requiring human judgment
-4. **Generates a verification report** with pass/fail status for each item
+After building, I run verification myself:
+- `clavix verify --latest` - Check the implementation
+- Run any automated tests
+- Build/compile to ensure no errors
 
-### Verification Report
+**Step 5: I report results**
 
-The verification report shows:
-- ✅ **Passed items** - Implementation covers the requirement
-- ❌ **Failed items** - Implementation does NOT cover (with reason why)
-- ⏭️ **Skipped items** - To be verified later
-- ➖ **N/A items** - Does not apply to this implementation
+You'll see a summary of:
+- What I built
+- What passed verification
+- Any issues (if they exist)
 
-### Fast Mode Prompts
+---
 
-Fast mode prompts don't have comprehensive checklists. When verifying a fast mode prompt:
-- A **basic checklist is generated** based on detected intent
-- Covers essential items (compiles, requirements met, no errors)
-- For comprehensive checklists, use `/clavix:deep` instead
+## Automatic Verification (I Handle This)
 
-### Verification Commands
+**I always verify after implementing. You don't need to ask.**
 
-```bash
-# Verify latest executed prompt
-clavix verify --latest
+### What Happens Automatically
 
-# Verify specific prompt
-clavix verify --id <prompt-id>
+After I finish building, I run verification myself:
 
-# Show verification status
-clavix verify --status
+1. **Load the checklist** - From your executed prompt (what to check)
+2. **Run automated tests** - Test suite, build, linting, type checking
+3. **Check each requirement** - Make sure everything was implemented
+4. **Generate a report** - Show you what passed and failed
 
-# Re-run failed items only
-clavix verify --retry-failed
+### What You'll See
 
-# Export verification report
-clavix verify --export markdown
-clavix verify --export json
 ```
+✓ Implementation complete for [prompt-id]
 
-### After Verification
-
-**If all items pass:**
-```bash
-# Cleanup executed prompts
-clavix prompts clear --executed
+Verification Results:
+✅ 8 items passed
+❌ 1 item needs attention: [specific issue]
 
-# Or archive the project
-/clavix:archive
+Would you like me to fix the failing item?
 ```
 
-**If items fail:**
-1. Review failed items and reasons
-2. Fix implementation issues
-3. Re-run verification: `clavix verify --retry-failed --id <prompt-id>`
+### Understanding the Symbols
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Passed - This works |
+| ❌ | Failed - Needs fixing |
+| ⏭️ | Skipped - Check later |
+| ➖ | N/A - Doesn't apply |
+
+### When Things Fail
+
+**I try to fix issues automatically:**
+
+If verification finds problems, I'll:
+1. Tell you what failed and why
+2. Offer to fix it
+3. Re-verify after fixing
+
+**If I can't fix it myself:**
+
+I'll explain what's wrong and what you might need to do:
+> "The database connection is failing - this might be a configuration issue.
+> Can you check that your `.env` file has the correct `DATABASE_URL`?"
+
+### Fast Mode vs Deep Mode Verification
+
+**Fast mode prompts:**
+- I generate a basic checklist based on what you asked for
+- Covers essentials: compiles, no errors, requirements met
+
+**Deep mode prompts:**
+- Use the comprehensive checklist from deep analysis
+- More thorough verification with edge cases
+
+**For more thorough verification next time, use `/clavix:deep`**
 
 ---
 
-## Prompt Management (CLI Commands)
+## Prompt Management (Commands I Run)
+
+These are commands I execute automatically - you don't need to run them.
 
-Prompts saved from `/clavix:fast` and `/clavix:deep` are stored in:
+**Where prompts live:**
 - Fast prompts: `.clavix/outputs/prompts/fast/`
 - Deep prompts: `.clavix/outputs/prompts/deep/`
 
-### List All Saved Prompts
-```bash
-clavix prompts list
-```
+### Commands I Use (Reference)
 
-Shows:
-- All saved prompts with age
-- Execution status (✓ executed / ○ pending)
-- Age warnings (OLD >7d, STALE >30d)
-- Storage statistics
+| What I Do | Command I Run |
+|-----------|---------------|
+| List saved prompts | `clavix prompts list` |
+| Get latest prompt | `clavix execute --latest` |
+| Get specific prompt | `clavix execute --id <id>` |
+| Run verification | `clavix verify --latest` |
+| Clean up executed | `clavix prompts clear --executed` |
+| Clean up stale (>30d) | `clavix prompts clear --stale` |
 
-### Cleanup Workflows
+### Automatic Cleanup
 
-**After executing prompts (recommended):**
-```bash
-clavix prompts clear --executed
-```
+After I finish implementing and verification passes:
+- I clean up executed prompts automatically
+- Old prompts (>30 days) get flagged as stale for removal
+- I keep your storage tidy
 
-**Remove stale prompts (>30 days):**
-```bash
-clavix prompts clear --stale
-```
+### The Prompt Lifecycle
 
-**Remove specific type:**
-```bash
-clavix prompts clear --fast
-clavix prompts clear --deep
 ```
-
-**Interactive cleanup:**
-```bash
-clavix prompts clear
+1. YOU CREATE   →  /clavix:fast or /clavix:deep
+2. I EXECUTE    →  /clavix:execute (you are here)
+3. I VERIFY     →  Automatic verification
+4. I CLEANUP    →  Remove executed prompts
 ```
 
-**Remove all (with safety checks):**
-```bash
-clavix prompts clear --all
-```
+---
 
-### Prompt Lifecycle
+## Finding Your Way Around
 
-```
-CREATE   → /clavix:fast or /clavix:deep
-EXECUTE  → /clavix:execute (you are here)
-CLEANUP  → clavix prompts clear --executed
-```
+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` |
 
-### Best Practices
+---
 
-**Regular cleanup schedule:**
-1. After executing prompts: Clear executed
-2. Weekly: Review and clear stale
-3. Before archiving PRD: Clear related prompts
+## When Things Go Wrong
 
-**Storage hygiene:**
-- Keep <20 active prompts for performance
-- Clear executed prompts regularly
-- Review prompts >7 days old
+### No Prompts Found
+
+If I can't find a saved prompt, I'll tell you:
+> "I don't see any saved prompts. Let's create one first!"
+
+Then you can run `/clavix:fast "your requirement"` and come back.
+
+### Prompt Is Old or Stale
+
+If your prompt is more than 7 days old:
+> "This prompt is a bit old. Want me to proceed anyway, or should we create a fresh one?"
+
+### Verification Keeps Failing
+
+If I can't get verification to pass after trying:
+> "I've tried a few fixes but this item keeps failing. Here's what's happening: [details]
+>
+> Would you like me to:
+> 1. Keep trying with a different approach
+> 2. Skip this check for now
+> 3. Show you what needs manual attention"
 
 ---
 
-## Error Recovery
+## Workflow Navigation
 
-**No prompts found:**
-```bash
-/clavix:fast "your requirement"
-```
-Then retry `/clavix:execute`.
+**Where you are:** Execute (building your prompt)
 
-**Too many old prompts:**
-```bash
-clavix prompts clear --executed
-```
+**How you got here:**
+1. `/clavix:fast` or `/clavix:deep` → Optimized your prompt
+2. **`/clavix:execute`** → Now building it (you are here)
+
+**What happens after:**
+- I verify automatically → Results shown
+- If all passes → Done! I clean up
+- If issues → `/clavix:verify` for detailed check
+
+**Related commands:**
+- `/clavix:fast` - Quick prompt optimization (previous step)
+- `/clavix:deep` - Comprehensive analysis (alternative previous step)
+- `/clavix:verify` - Detailed verification (if needed)
+- `/clavix:archive` - Archive when fully done
 
 ---
 
-## Agent Transparency (v4.7)
+## Agent Transparency (v4.9)
 
-### File Format Reference
-{{INCLUDE:agent-protocols/file-formats.md}}
+### CLI Reference (Commands I Execute)
+{{INCLUDE:agent-protocols/cli-reference.md}}
 
 ### Error Handling
 {{INCLUDE:agent-protocols/error-handling.md}}
 
 ### Agent Decision Rules
 {{INCLUDE:agent-protocols/decision-rules.md}}
+
+### Recovery Patterns
+{{INCLUDE:troubleshooting/vibecoder-recovery.md}}

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."**
@@ -186,22 +193,28 @@ Clavix provides **Clavix Intelligence™** that automatically detects intent and
 
 ---
 
-## Agent Transparency (v4.6)
+## Agent Transparency (v4.9)
 
-### Quality Output Format
-{{INCLUDE:agent-protocols/quality-output.md}}
+### CLI Reference (Commands I Execute)
+{{INCLUDE:agent-protocols/cli-reference.md}}
 
-### Agent Decision Rules
-{{INCLUDE:agent-protocols/decision-rules.md}}
+### How to Explain Improvements
+{{INCLUDE:sections/improvement-explanations.md}}
 
-### Assertion Checkpoints
-{{INCLUDE:agent-protocols/assertion-checkpoints.md}}
+### Quality Dimensions (Plain English)
+{{INCLUDE:references/quality-dimensions.md}}
 
-### Escalation Factors (Smart Triage)
+### When to Recommend Deep Mode
 {{INCLUDE:sections/escalation-factors.md}}
 
-### Patterns Applied
-{{INCLUDE:sections/pattern-visibility.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}}
 
 ---
 
@@ -284,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)
@@ -379,19 +417,20 @@ Confirm:
 
 ## ⛔ 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)
+Run this command yourself 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. Great!
 
-**If verification fails**:
-- Check if file was saved to `.clavix/outputs/prompts/fast/`
-- Retry the save operation
-- Check file permissions
+**If it failed**:
+- Create the directory: `mkdir -p .clavix/outputs/prompts/fast`
+- Try saving again
+- If still failing, tell the user: "I had trouble saving, but here's your improved prompt..."
 
 ### Required Response Ending
 
@@ -399,26 +438,28 @@ clavix prompts list
 ```
 ✅ 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: Don't start implementing. Don't write code. Your job is done.**
+Wait for the user to decide what to do next.
 
 ---
 
-### Prompt Management (CLI Commands)
+### Prompt Management (Commands You Run)
+
+These are commands you execute when needed - don't ask the user to run them.
 
-**List all saved prompts:**
+**Check saved prompts:**
 ```bash
 clavix prompts list
 ```
 
-**Cleanup after execution:**
+**Cleanup (run when user asks or during maintenance):**
 ```bash
-clavix prompts clear --executed  # Remove executed prompts
-clavix prompts clear --stale     # Remove >30 day old prompts
-clavix prompts clear --fast      # Remove all fast prompts
+clavix prompts clear --executed  # Remove implemented prompts
+clavix prompts clear --stale     # Remove old prompts (>30 days)
 ```
 
 ## Workflow Navigation