clavix 4.8.1 → 4.10.0

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

@@ -0,0 +1,214 @@
+## CLI Commands Reference (For Agent Execution)
+
+These are commands YOU (the agent) run automatically. Never ask the user to run these - you execute them and report results.
+
+---
+
+### Prompt Management Commands
+
+#### `clavix fast "prompt"`
+**What it does:** Quickly improves a prompt and saves it
+**When to run:** After user provides a prompt for optimization
+**You say:** "Let me improve this prompt for you..."
+**Example:**
+```bash
+clavix fast "build a todo app"
+```
+
+#### `clavix deep "prompt"`
+**What it does:** Comprehensive prompt analysis with alternatives and edge cases
+**When to run:** When prompt needs thorough analysis (complex requirements, low quality score)
+**You say:** "This needs a deeper look - let me analyze it thoroughly..."
+**Example:**
+```bash
+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
+**You say:** "Let me check your saved prompts..."
+**Example output:**
+```
+📋 Saved Prompts (3 total)
+  fast-20250126-143022-a3f2  [not executed]  "build a todo app..."
+  deep-20250126-150000-b4c3  [executed]      "authentication system..."
+```
+
+#### `clavix prompts clear --executed`
+**What it does:** Removes prompts that have already been implemented
+**When to run:** During cleanup or when user wants to tidy up
+**You say:** "Cleaning up executed prompts..."
+
+#### `clavix prompts clear --stale`
+**What it does:** Removes prompts older than 30 days
+**When to run:** When storage is cluttered with old prompts
+**You say:** "Removing old prompts to keep things tidy..."
+
+---
+
+### Implementation Commands
+
+#### `clavix execute --latest`
+**What it does:** Retrieves the most recent saved prompt for implementation
+**When to run:** When starting implementation workflow
+**You say:** "Getting your latest prompt ready for implementation..."
+**Flags:**
+- `--latest` - Get most recent prompt
+- `--fast` - Filter to fast prompts only
+- `--deep` - Filter to deep prompts only
+- `--id <prompt-id>` - Get specific prompt
+
+#### `clavix implement`
+**What it does:** Starts implementation session from task plan
+**When to run:** After PRD and tasks exist, ready to build
+**You say:** "Starting implementation - let me check your tasks..."
+**Flags:**
+- `--commit-strategy=per-task` - Commit after each task
+- `--commit-strategy=per-phase` - Commit after each phase
+- `--list` - Show available tasks
+
+#### `clavix task-complete <task-id>`
+**What it does:** Marks a task as done, updates tracking, optionally commits
+**When to run:** IMMEDIATELY after finishing each task implementation
+**You say:** "Marking that task as complete..."
+**CRITICAL:** Never manually edit tasks.md checkboxes - always use this command
+**Example:**
+```bash
+clavix task-complete phase-1-setup-project-1
+```
+**Flags:**
+- `--no-git` - Skip git commit
+- `--force` - Complete even if already done
+
+#### `clavix verify --latest`
+**What it does:** Runs verification checks against implementation
+**When to run:** After implementation, before considering work done
+**You say:** "Running verification checks..."
+**Flags:**
+- `--latest` - Verify most recent executed prompt
+- `--id <prompt-id>` - Verify specific prompt
+- `--status` - Show verification status only
+- `--retry-failed` - Re-run only failed checks
+- `--export markdown` - Generate verification report
+- `--run-hooks` - Run automated tests (default: true)
+
+---
+
+### Planning Commands
+
+#### `clavix prd`
+**What it does:** Launches PRD generation workflow
+**When to run:** When user wants to plan a feature/project
+**You say:** "Let's plan this out properly..."
+
+#### `clavix plan`
+**What it does:** Generates task breakdown from PRD
+**When to run:** After PRD exists, ready to create tasks
+**You say:** "Creating your implementation tasks..."
+**Flags:**
+- `--project <name>` - Specify which project
+- `--overwrite` - Regenerate existing tasks
+
+---
+
+### Project Management Commands
+
+#### `clavix archive <project-name>`
+**What it does:** Archives completed project
+**When to run:** When all tasks are done and verified
+**You say:** "Archiving this project for your records..."
+**Flags:**
+- `--force` - Archive even if incomplete
+- `--delete` - Permanently delete instead
+- `--list` - Show archived projects
+- `--restore <name>` - Restore from archive
+
+#### `clavix list`
+**What it does:** Shows sessions and outputs
+**When to run:** To find projects, check progress
+**You say:** "Let me show you what we have..."
+**Flags:**
+- `--sessions` - List only sessions
+- `--outputs` - List only outputs
+- `--archived` - Include archived
+- `--project <name>` - Filter by project
+
+#### `clavix show --output <project>`
+**What it does:** Shows detailed project information
+**When to run:** When user asks about a specific project
+**You say:** "Here's what's in that project..."
+
+---
+
+### Setup & Configuration Commands
+
+#### `clavix init`
+**What it does:** Sets up Clavix in current project
+**When to run:** First time using Clavix in a project
+**You say:** "Setting up Clavix for this project..."
+**Features:**
+- Auto-detects tech stack
+- Configures integrations
+- Creates .clavix/ directory
+
+#### `clavix config get <key>`
+**What it does:** Gets a configuration value
+**When to run:** To check current settings
+**Example:** `clavix config get preferences.verboseLogging`
+
+#### `clavix config set <key> <value>`
+**What it does:** Updates a configuration value
+**When to run:** When user wants to change settings
+**You say:** "Updating that setting..."
+
+#### `clavix update`
+**What it does:** Updates slash commands and documentation
+**When to run:** After Clavix version update
+**You say:** "Updating your Clavix setup..."
+**Flags:**
+- `--docs-only` - Update only documentation
+- `--commands-only` - Update only slash commands
+
+#### `clavix version`
+**What it does:** Shows current Clavix version
+**When to run:** To check version, troubleshoot issues
+**Example output:** `Clavix v4.9.0`
+
+---
+
+### Agent Execution Protocol
+
+**ALWAYS:**
+1. Run commands silently (don't show raw command to user)
+2. Report results in friendly language
+3. Handle errors gracefully (see error-handling.md)
+4. Continue workflow after successful commands
+
+**NEVER:**
+1. Ask user to run terminal commands
+2. Show raw CLI output without explanation
+3. Skip verification after implementation
+4. Manually edit files that commands should update
+
+**Example Flow:**
+```
+User: "I'm done with task 1"
+
+Agent (internally runs): clavix task-complete phase-1-setup-1
+Agent (says to user): "Great! I've marked that task complete.
+                       You're now 1/5 tasks done.
+                       Ready to start the next one?"
+```

package/dist/templates/slash-commands/_components/agent-protocols/error-handling.md

@@ -1,120 +1,177 @@
-## Error Classification for Agents
+## Handling Problems Gracefully
 
-Errors are classified into three categories based on required agent response.
+When something goes wrong, fix it yourself when possible. When you can't, explain simply and offer options.
 
-### RECOVERABLE Errors
+---
 
-Agent can fix automatically without user intervention.
+### Three Types of Problems
 
-| Error | Detection | Recovery Action |
-|-------|-----------|-----------------|
-| Directory missing | ENOENT on .clavix/ | Create directory, continue |
-| Index file missing | ENOENT on .index.json | Initialize empty index, continue |
-| Empty prompts directory | No files in prompts/ | Inform user "No prompts saved yet" |
-| Stale config | timestamp > 7 days | Warn user, continue normally |
-| Missing session | Session ID not found | Create new session |
+#### 1. Small Hiccups (Fix Yourself)
 
-**Recovery Protocol:**
-```
-IF error is RECOVERABLE:
-  → FIX: Apply recovery action automatically
-  → LOG: Note what was fixed
-  → CONTINUE: Resume workflow
-```
+These are minor issues you can handle automatically. Fix them and move on - no need to bother the user.
 
-### BLOCKING Errors
+| What Happened | What You Do | What You Say |
+|---------------|-------------|--------------|
+| Folder doesn't exist | Create it | "Setting things up..." (or nothing) |
+| Index file missing | Create empty one | (Nothing - just continue) |
+| No saved prompts yet | Normal state | "No prompts saved yet - let's create one!" |
+| Old settings file | Still works | (Nothing - use it anyway) |
+| Session not found | Start new one | (Nothing - create new) |
 
-Agent must stop and ask user before proceeding.
+**Your approach:**
+1. Fix the issue automatically
+2. Maybe mention it briefly: "Setting things up..."
+3. Continue with what you were doing
 
-| Error | Detection | Agent Action |
-|-------|-----------|--------------|
-| Task not found | task-complete returns "not found" | ASK: "Task [id] not found in tasks.md. Verify the task ID?" |
-| Multiple PRDs | >1 project detected | ASK: "Multiple projects found: [list]. Which one?" |
-| Ambiguous intent | confidence <50% | ASK: "Unclear intent. Is this: [A] / [B] / [C]?" |
-| Missing PRD for plan | No PRD files exist | ASK: "No PRD found. Create one with /clavix:prd first?" |
-| Task blocked | External dependency | ASK: "Task blocked by [reason]. Skip or resolve?" |
-| Overwrite conflict | File already exists | ASK: "File exists. Overwrite / Rename / Cancel?" |
+---
 
-**Blocking Protocol:**
-```
-IF error is BLOCKING:
-  → STOP: Halt current operation
-  → EXPLAIN: Clear description of the issue
-  → OPTIONS: Present available choices
-  → WAIT: For user response before continuing
-```
+#### 2. Need User Input (Ask Nicely)
 
-### UNRECOVERABLE Errors
+These need a decision from the user. Stop, explain simply, and offer clear choices.
 
-Agent must stop completely and report to user for manual resolution.
+| What Happened | What You Ask |
+|---------------|--------------|
+| Can't find that task | "I can't find task [X]. Let me show you what's available..." |
+| Multiple projects found | "I found a few projects here. Which one should we work on?" |
+| Not sure what you want | "I want to make sure I understand - is this about [A] or [B]?" |
+| No plan exists yet | "I don't see a plan for this project. Want to create one first?" |
+| Task is blocked | "This task needs [thing] first. Should I work on that, or skip for now?" |
+| File already exists | "This file already exists. Should I replace it, rename the new one, or cancel?" |
 
-| Error | Detection | Agent Action |
-|-------|-----------|--------------|
-| Permission denied | EACCES error code | STOP. Report: "Permission denied on [path]. Check file permissions." |
-| Corrupt JSON | JSON.parse throws | STOP. Report: "Config file corrupted at [path]. Manual fix required." |
-| Git conflict | git command fails with conflict | STOP. Report: "Git conflict detected. Resolve manually before continuing." |
-| Disk full | ENOSPC error | STOP. Report: "Disk full. Free up space before continuing." |
-| Network timeout | ETIMEDOUT on external | STOP. Report: "Network timeout. Check connection and retry." |
-| Invalid task ID format | Regex mismatch | STOP. Report: "Invalid task ID format: [id]. Expected: phase-N-name-M" |
+**Your approach:**
+1. Stop what you're doing
+2. Explain the situation simply
+3. Give 2-3 clear options
+4. Wait for their answer
 
-**Unrecoverable Protocol:**
-```
-IF error is UNRECOVERABLE:
-  → STOP: Halt all operations immediately
-  → REPORT: Exact error with context
-  → GUIDE: Manual steps to resolve
-  → NO RETRY: Do not attempt automatic recovery
-```
+**Example:**
+> "I found a few projects in this folder:
+>
+> 1. **todo-app** - 3 tasks done, 2 to go
+> 2. **auth-feature** - Not started yet
+>
+> Which one should we work on?"
+
+---
+
+#### 3. Real Problems (Need Their Help)
+
+These are issues you can't fix. Stop completely and explain what they need to do.
+
+| What Happened | What You Say |
+|---------------|--------------|
+| Permission denied | "I can't write to that folder - it looks like a permissions issue. You might need to check the folder settings." |
+| Config file broken | "One of the settings files got corrupted. You might need to delete it and start fresh, or try to fix it manually." |
+| Git conflict | "There's a git conflict that needs your attention. Once you resolve it, we can continue." |
+| Disk full | "Looks like the disk is full - I can't save anything. Once you free up some space, we can try again." |
+| Connection timeout | "I'm having trouble connecting. Could be a network issue - want to try again?" |
+| Invalid format | "That doesn't look quite right - [specific issue]. Could you check and try again?" |
+
+**Your approach:**
+1. Stop immediately
+2. Explain what went wrong (simply!)
+3. Tell them what needs to happen to fix it
+4. Don't try to fix it yourself
+
+**Example:**
+> "I can't continue - there's a git conflict in some files.
+>
+> Files with conflicts:
+> - src/components/Header.tsx
+> - src/utils/auth.ts
+>
+> Once you resolve these (pick which changes to keep), let me know and we'll continue."
+
+---
 
-### Error Response Templates
+### How to Explain Problems
 
-**Recoverable:**
+**Don't say this:**
+> "ENOENT: no such file or directory, open '.clavix/outputs/prompts/fast/.index.json'"
+
+**Say this:**
+> "Setting up your prompt storage..." (then just create the file)
+
+**Don't say this:**
+> "Error: EACCES: permission denied, mkdir '/usr/local/clavix'"
+
+**Say this:**
+> "I can't create files in that location - it needs admin permissions.
+> Try running from your project folder instead?"
+
+**Don't say this:**
+> "SyntaxError: Unexpected token } in JSON at position 1523"
+
+**Say this:**
+> "The settings file got corrupted somehow. I can start fresh if you want,
+> or you can try to fix it manually."
+
+---
+
+### Recovery Templates
+
+**For small hiccups (you fixed it):**
 ```
-[Fixed] Created missing .clavix/ directory. Continuing...
+[If worth mentioning]
+"Small hiccup - I've handled it. Moving on..."
+
+[Usually just]
+(Say nothing, continue working)
 ```
 
-**Blocking:**
+**For needing user input:**
 ```
-[Blocked] Multiple projects found. Please select:
-  1. auth-feature (75% complete)
-  2. api-refactor (0% complete)
+"Quick question: [simple explanation of situation]
 
-Which project should I work with?
+Would you like me to:
+1. [Option A]
+2. [Option B]
+3. [Option C - usually 'skip for now']"
 ```
 
-**Unrecoverable:**
+**For real problems:**
 ```
-[Error] Cannot continue - manual intervention required.
+"I ran into something I can't fix myself.
 
-Issue: Permission denied writing to /path/to/file
-Cause: Insufficient file system permissions
+What happened: [simple explanation]
 
-To resolve:
-  1. Check ownership: ls -la /path/to/
-  2. Fix permissions: chmod 755 /path/to/
-  3. Retry the operation
+To fix this, you'll need to:
+1. [Step 1]
+2. [Step 2]
 
-Once resolved, run the command again.
+Once that's done, let me know and we'll pick up where we left off."
 ```
 
-### Error Detection Patterns
+---
+
+### Common Patterns (Internal Reference)
+
+**File/Folder Issues:**
+- File not found → Usually create it automatically
+- Already exists → Ask: replace, rename, or cancel?
+- Permission denied → Stop, explain, user needs to fix
+- Disk full → Stop, explain, user needs to free space
+
+**Git Issues:**
+- CONFLICT detected → Stop, list files, user must resolve
+- Not a git repo → Ask if they want to initialize one
+- Nothing to commit → Fine, just continue
+
+**Settings Issues:**
+- Can't read/parse file → Stop, explain, might need to delete and restart
+- Empty file → Usually just initialize with defaults
 
-**File System Errors:**
-- `ENOENT` - File/directory not found → Usually RECOVERABLE
-- `EACCES` - Permission denied → UNRECOVERABLE
-- `EEXIST` - Already exists → BLOCKING (ask overwrite)
-- `ENOSPC` - No space left → UNRECOVERABLE
+**Task Issues:**
+- Task not found → Show available tasks, ask which one
+- Already completed → Tell them, show what's left
+- Wrong order → Explain the dependency, offer to fix order
 
-**Git Errors:**
-- "CONFLICT" in output → UNRECOVERABLE
-- "not a git repository" → BLOCKING (ask to init)
-- "nothing to commit" → RECOVERABLE (skip commit)
+---
 
-**JSON Errors:**
-- `SyntaxError: Unexpected token` → UNRECOVERABLE
-- Empty file → RECOVERABLE (initialize default)
+### The Golden Rules
 
-**Task Errors:**
-- Task ID not in tasks.md → BLOCKING
-- Checkbox already checked → RECOVERABLE (skip)
-- Invalid phase number → UNRECOVERABLE
+1. **Fix it yourself if you can** - Don't bother users with small stuff
+2. **Explain simply when you can't** - No error codes, no jargon
+3. **Always offer a path forward** - Never leave them stuck
+4. **Preserve their work** - Never lose what they've done
+5. **Stay calm and friendly** - Problems happen, no big deal

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.