clavix 5.0.1 → 5.1.1

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

@@ -0,0 +1,284 @@
+# Clavix Agent Manual (v5.1)
+
+This is the consolidated agent protocol reference. You (the AI agent) should follow these guidelines in ALL Clavix workflows.
+
+---
+
+## Core Principle: Agentic-First Architecture
+
+Clavix v5 follows an **agentic-first architecture**. This means:
+
+1. **You execute workflows directly** using your native tools (Write, Read, Edit, Bash)
+2. **Slash commands are templates** that you read and follow - not CLI commands
+3. **CLI commands are ONLY for setup** (`clavix init`, `clavix update`, `clavix config`)
+4. **You save outputs to `.clavix/outputs/`** using your Write tool
+
+**DO NOT:**
+- Try to run `clavix` CLI commands during workflows (they don't exist for workflows)
+- Ask the user to run terminal commands for workflow operations
+- Skip verification after completing work
+
+---
+
+## File System Structure
+
+```
+.clavix/
+├── config.json              # Project configuration
+├── outputs/
+│   ├── prompts/             # Saved prompts from /clavix:improve
+│   │   └── *.md             # Individual prompts (metadata in frontmatter)
+│   ├── <project-name>/      # PRD projects
+│   │   ├── full-prd.md      # Comprehensive PRD
+│   │   ├── quick-prd.md     # AI-optimized summary
+│   │   └── tasks.md         # Implementation tasks
+│   └── archive/             # Archived projects
+└── commands/                # Slash command templates (managed by clavix update)
+```
+
+---
+
+## REQUIRED: Output Verification Protocol
+
+**After EVERY file operation, verify success:**
+
+| Step | Action | How to Verify |
+|------|--------|---------------|
+| 1 | Write file | Use Write tool |
+| 2 | Verify exists | Use Read tool to confirm file was created |
+| 3 | Report to user | Show ACTUAL file path (not placeholder) |
+
+**⚠️ Never tell the user a file was saved without verifying it exists.**
+
+---
+
+## Handling Problems Gracefully
+
+When something goes wrong, fix it yourself when possible. When you can't, explain simply and offer options.
+
+### Three Types of Problems
+
+#### 1. Small Hiccups (Fix Yourself)
+
+These are minor issues you can handle automatically. Fix them and move on.
+
+| What Happened | What You Do |
+|---------------|-------------|
+| Folder doesn't exist | Create it |
+| Index file missing | Create empty one |
+| No saved prompts yet | Normal state - inform user |
+| Old settings file | Still works - use it |
+
+**Your approach:**
+1. Fix the issue automatically
+2. Maybe mention it briefly: "Setting things up..."
+3. Continue with what you were doing
+
+#### 2. Need User Input (Ask Nicely)
+
+These need a decision from the user. Stop, explain simply, and offer clear choices.
+
+| 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. Which one should we work on?" |
+| Not sure what you want | "I want to make sure I understand - is this about [A] or [B]?" |
+| File already exists | "This file already exists. Replace, rename, or cancel?" |
+
+**Your approach:**
+1. Stop what you're doing
+2. Explain the situation simply
+3. Give 2-3 clear options
+4. Wait for their answer
+
+#### 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." |
+| Config file broken | "Settings file got corrupted. You might need to delete it and start fresh." |
+| Git conflict | "There's a git conflict that needs your attention." |
+| Disk full | "Disk is full - I can't save anything." |
+
+**Your approach:**
+1. Stop immediately
+2. Explain what went wrong (simply!)
+3. Tell them what needs to happen to fix it
+
+### The Golden Rules
+
+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
+
+---
+
+## Agent Decision Rules
+
+These rules define deterministic agent behavior. Follow exactly.
+
+### Rule 1: Quality-Based Decisions
+
+```
+IF quality < 60%:
+  → ACTION: Suggest comprehensive analysis
+  → SAY: "Quality is [X]%. Consider comprehensive depth."
+
+IF quality >= 60% AND quality < 80%:
+  → ACTION: Proceed with optimization
+  → SHOW: Improvement suggestions
+
+IF quality >= 80%:
+  → ACTION: Ready to use
+  → SAY: "Quality is good ([X]%). Ready to proceed."
+```
+
+### Rule 2: Intent Confidence
+
+```
+IF confidence >= 85%:
+  → ACTION: Proceed with detected intent
+
+IF confidence 70-84%:
+  → ACTION: Proceed, note secondary intent if >25%
+
+IF confidence 50-69%:
+  → ACTION: Ask user to confirm
+
+IF confidence < 50%:
+  → ACTION: Cannot proceed autonomously
+  → ASK: "I'm unclear on intent. Is this: [A] | [B] | [C]?"
+```
+
+### Rule 3: File Operations
+
+```
+BEFORE writing files:
+  → CHECK: Target directory exists
+  → IF not exists: Create directory first
+
+AFTER writing files:
+  → VERIFY: File was created successfully
+  → IF failed: Report error, suggest manual action
+```
+
+### Rule 4: Task Completion (Implementation Mode)
+
+```
+AFTER implementing task:
+  → EDIT tasks.md: Change - [ ] to - [x] for completed task
+
+IF edit succeeds:
+  → SHOW: Next task automatically
+  → CONTINUE with next task
+
+IF edit fails:
+  → SHOW error to user
+  → ASK: "Task completion failed. How to proceed?"
+```
+
+### Rule 5: Error Recovery
+
+```
+IF pattern application fails:
+  → LOG: Which pattern failed
+  → CONTINUE: With remaining patterns
+  → REPORT: "Pattern [X] skipped due to error"
+
+IF file write fails:
+  → RETRY: Once with alternative path
+  → IF still fails: Report error with manual steps
+
+IF user prompt is empty/invalid:
+  → ASK: For valid input
+  → NEVER: Proceed with assumption
+```
+
+### Rule 6: Execution Verification
+
+```
+BEFORE completing response:
+  → VERIFY all checkpoints met for current mode
+  → IF any checkpoint failed:
+    → REPORT which checkpoint failed
+    → EXPLAIN why it failed
+    → SUGGEST recovery action
+```
+
+---
+
+## What You Should NEVER Do
+
+❌ **Don't silently skip tasks** - Always tell user if something was skipped
+❌ **Don't make assumptions** - When in doubt, ask
+❌ **Don't give up too easily** - Try to recover first
+❌ **Don't overwhelm with options** - Max 3 choices
+❌ **Don't use technical language** - Keep it friendly
+❌ **Don't blame the user** - Even if they caused the issue
+❌ **Don't claim features don't exist** - Check before saying no
+❌ **Don't output "saved" without verification** - That's lying to the user
+
+---
+
+## Mode Boundaries
+
+Each Clavix command has a specific mode. Stay within your mode:
+
+| Mode | What You DO | What You DON'T DO |
+|------|-------------|-------------------|
+| **Improve** | Analyze and optimize prompts | Implement the feature described |
+| **PRD** | Guide strategic questions, create PRD | Write implementation code |
+| **Plan** | Generate task breakdown | Start implementing tasks |
+| **Implement** | Build tasks/prompts | Skip to next task without marking complete |
+| **Start** | Gather requirements conversationally | Start implementing |
+| **Summarize** | Extract requirements from conversation | Implement the requirements |
+| **Verify** | Check implementation, run tests | Fix issues (only report them) |
+| **Archive** | Move completed projects | Delete without confirmation |
+
+**If you catch yourself crossing mode boundaries:**
+1. STOP immediately
+2. Say: "I apologize - I was [mistake]. Let me return to [correct mode]."
+3. Resume correct workflow
+
+---
+
+## Communication Style
+
+**Don't say this:**
+> "ENOENT: no such file or directory, open '.clavix/outputs/prompts/'"
+
+**Say this:**
+> "Setting up your prompt storage..." (then just create the directory)
+
+**Don't say this:**
+> "Error: EACCES: permission denied"
+
+**Say this:**
+> "I can't create files in that location - it needs different permissions."
+
+**Don't say this:**
+> "SyntaxError: Unexpected token } in JSON"
+
+**Say this:**
+> "The settings file got corrupted. I can start fresh if you want."
+
+---
+
+## Verification Block Template
+
+At the end of workflows that produce output, include verification:
+
+```
+## Clavix Execution Verification
+- [x] Mode: {improve|prd|plan|implement|verify|archive}
+- [x] Output created: {actual file path}
+- [x] Verification: {how you verified it exists}
+```
+
+---
+
+*This manual is included in all Clavix slash command templates. Version 5.1*

package/dist/types/agent.d.ts

@@ -26,10 +26,6 @@ export interface IntegrationFeatures {
         separator: ':' | '-';
     };
 }
-/**
- * @deprecated Use IntegrationFeatures instead. Will be removed in v4.0.0
- */
-export type ProviderFeatures = IntegrationFeatures;
 export interface ValidationResult {
     valid: boolean;
     errors?: string[];

package/dist/types/config.js

@@ -2,7 +2,7 @@
  * Configuration types for Clavix
  */
 export const DEFAULT_CONFIG = {
-    version: '3.5.0',
+    version: '5.1.1',
     integrations: [],
     templates: {
         prdQuestions: 'default',

package/dist/utils/agent-error-messages.d.ts

@@ -20,12 +20,12 @@ export declare class AgentErrorMessages {
     static noTasksFound(projectName: string): string;
     /**
      * Error: .clavix-implement-config.json not found
-     * Used by: task-complete.ts, implement workflow
+     * Used by: implement workflow
      */
     static configNotFound(): string;
     /**
      * Error: Specified task ID not found in tasks.md
-     * Used by: task-complete.ts
+     * Used by: implement workflow
      */
     static taskNotFound(taskId: string, availableTasks: Array<{
         id: string;
@@ -54,7 +54,7 @@ export declare class AgentErrorMessages {
     static tasksExistWithProgress(completedCount: number, totalCount: number): string;
     /**
      * Error: Git repository not initialized
-     * Used by: implement.ts, task-complete.ts when git features expected
+     * Used by: implement workflow when git features expected
      */
     static gitNotInitialized(): string;
     /**
@@ -74,7 +74,7 @@ export declare class AgentErrorMessages {
     static cliExecutionFailed(command: string, exitCode: number, stderr?: string): string;
     /**
      * Error: Invalid task ID format
-     * Used by: task-complete.ts
+     * Used by: implement workflow
      */
     static invalidTaskIdFormat(taskId: string): string;
     /**
@@ -84,7 +84,7 @@ export declare class AgentErrorMessages {
     static sessionNotFound(sessionId: string): string;
     /**
      * Warning: Task already completed
-     * Used by: task-complete.ts when marking already-done task
+     * Used by: implement workflow when marking already-done task
      */
     static taskAlreadyCompleted(taskId: string): string;
 }

package/dist/utils/agent-error-messages.js

@@ -33,7 +33,7 @@ export class AgentErrorMessages {
     }
     /**
      * Error: .clavix-implement-config.json not found
-     * Used by: task-complete.ts, implement workflow
+     * Used by: implement workflow
      */
     static configNotFound() {
         return ('Configuration file not found: .clavix-implement-config.json\n\n' +
@@ -45,7 +45,7 @@ export class AgentErrorMessages {
     }
     /**
      * Error: Specified task ID not found in tasks.md
-     * Used by: task-complete.ts
+     * Used by: implement workflow
      */
     static taskNotFound(taskId, availableTasks) {
         const taskList = availableTasks
@@ -114,7 +114,7 @@ export class AgentErrorMessages {
     }
     /**
      * Error: Git repository not initialized
-     * Used by: implement.ts, task-complete.ts when git features expected
+     * Used by: implement workflow when git features expected
      */
     static gitNotInitialized() {
         return ('Git repository not detected\n\n' +
@@ -168,7 +168,7 @@ export class AgentErrorMessages {
     }
     /**
      * Error: Invalid task ID format
-     * Used by: task-complete.ts
+     * Used by: implement workflow
      */
     static invalidTaskIdFormat(taskId) {
         return (`Invalid task ID format: ${taskId}\n\n` +
@@ -194,7 +194,7 @@ export class AgentErrorMessages {
     }
     /**
      * Warning: Task already completed
-     * Used by: task-complete.ts when marking already-done task
+     * Used by: implement workflow when marking already-done task
      */
     static taskAlreadyCompleted(taskId) {
         return (`Task already completed: ${taskId}\n\n` +

package/dist/utils/error-utils.d.ts

@@ -32,12 +32,6 @@ interface NodeJSError extends Error {
  * Type guard to check if error is a NodeJS error with code property
  */
 export declare function isNodeError(error: unknown): error is NodeJSError;
-/**
- * Handles CLI errors, formatting OCLIF errors nicely and falling back to default handler.
- * @param error The error to handle
- * @param defaultHandler The default handler function (usually handle from @oclif/core)
- * @param exitFn Optional exit function (defaults to process.exit)
- */
-export declare function handleCliError(error: any, defaultHandler: (err: any) => Promise<void>, exitFn?: (code: number) => void): Promise<void>;
+export declare function handleCliError(error: unknown, defaultHandler: (err: unknown) => Promise<void>, exitFn?: (code: number) => void): Promise<void>;
 export {};
 //# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.js

@@ -61,22 +61,23 @@ export function toError(error) {
  * Type guard to check if error is a NodeJS error with code property
  */
 export function isNodeError(error) {
-    return (isError(error) &&
-        'code' in error &&
-        typeof error.code === 'string');
+    return isError(error) && 'code' in error && typeof error.code === 'string';
 }
-/**
- * Handles CLI errors, formatting OCLIF errors nicely and falling back to default handler.
- * @param error The error to handle
- * @param defaultHandler The default handler function (usually handle from @oclif/core)
- * @param exitFn Optional exit function (defaults to process.exit)
- */
 export async function handleCliError(error, defaultHandler, exitFn = process.exit) {
+    // Type guard for OCLIF errors
+    const isOclifError = (err) => {
+        return (err !== null &&
+            typeof err === 'object' &&
+            'oclif' in err &&
+            err.oclif !== null &&
+            typeof err.oclif === 'object' &&
+            'exit' in err.oclif);
+    };
     // For CLIError, show only the formatted message
-    if (error && error.oclif && error.oclif.exit !== undefined) {
+    if (isOclifError(error)) {
         // Format error message (hints are now included in error.message)
         console.error(' ›   Error: ' + error.message);
-        exitFn(error.oclif.exit);
+        exitFn(error.oclif?.exit ?? 1);
         return;
     }
     // For other errors, use default handler

package/dist/utils/toml-templates.js

@@ -23,7 +23,10 @@ export function parseTomlSlashCommand(content, templateName, providerName) {
     while (promptLines.length > 0 && /^\s*(description\s*=|prompt\s*=)/.test(promptLines[0])) {
         promptLines.shift();
     }
-    promptBody = promptLines.join('\n').replace(/^\n+/, '').replace(/[\s]+$/, '');
+    promptBody = promptLines
+        .join('\n')
+        .replace(/^\n+/, '')
+        .replace(/[\s]+$/, '');
     return {
         description: descriptionMatch ? descriptionMatch[2] : '',
         prompt: promptBody,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.0.1",
+  "version": "5.1.1",
   "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -70,20 +70,15 @@
     "@oclif/plugin-help": "^6.2.35",
     "chalk": "^5.6.2",
     "fs-extra": "^11.3.2",
-    "handlebars": "^4.7.8",
-    "inquirer": "^12.11.1",
-    "json5": "^2.2.3",
-    "uuid": "^9.0.1"
+    "inquirer": "^12.11.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@oclif/test": "^4.1.15",
     "@types/fs-extra": "^11.0.4",
-    "@types/handlebars": "^4.0.40",
     "@types/inquirer": "^9.0.9",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
-    "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^8.46.4",
     "@typescript-eslint/parser": "^8.46.4",
     "copyfiles": "^2.4.1",