clavix 4.8.0 → 4.9.0

package/dist/core/adapters/amp-adapter.d.ts

@@ -13,6 +13,9 @@ export declare class AmpAdapter extends BaseAdapter {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
         supportsExecutableCommands: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Amp is available in the project

package/dist/core/adapters/amp-adapter.js

@@ -14,6 +14,7 @@ export class AmpAdapter extends BaseAdapter {
         supportsSubdirectories: false,
         supportsFrontmatter: false,
         supportsExecutableCommands: true,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Amp is available in the project

package/dist/core/adapters/cline-adapter.d.ts

@@ -19,6 +19,9 @@ export declare class ClineAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Cline is available in the project

package/dist/core/adapters/cline-adapter.js

@@ -20,6 +20,7 @@ export class ClineAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: false,
         supportsFrontmatter: false,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Cline is available in the project

package/dist/core/adapters/codebuddy-adapter.d.ts

@@ -14,6 +14,9 @@ export declare class CodeBuddyAdapter extends BaseAdapter {
         supportsFrontmatter: boolean;
         argumentPlaceholder: string;
         frontmatterFields: string[];
+        commandFormat: {
+            separator: "-";
+        };
     };
     detectProject(): Promise<boolean>;
     getCommandPath(): string;

package/dist/core/adapters/codebuddy-adapter.js

@@ -16,6 +16,7 @@ export class CodeBuddyAdapter extends BaseAdapter {
         supportsFrontmatter: true,
         argumentPlaceholder: '$1',
         frontmatterFields: ['description', 'argument-hint'],
+        commandFormat: { separator: '-' },
     };
     async detectProject() {
         if (await FileSystem.exists('.codebuddy')) {

package/dist/core/adapters/codex-adapter.d.ts

@@ -14,6 +14,9 @@ export declare class CodexAdapter extends BaseAdapter {
         supportsFrontmatter: boolean;
         argumentPlaceholder: string;
         frontmatterFields: string[];
+        commandFormat: {
+            separator: "-";
+        };
     };
     detectProject(): Promise<boolean>;
     getCommandPath(): string;

package/dist/core/adapters/codex-adapter.js

@@ -16,6 +16,7 @@ export class CodexAdapter extends BaseAdapter {
         supportsFrontmatter: true,
         argumentPlaceholder: '$ARGUMENTS',
         frontmatterFields: ['description', 'argument-hint'],
+        commandFormat: { separator: '-' },
     };
     async detectProject() {
         const codexDir = path.join(this.getHomeDir(), '.codex');

package/dist/core/adapters/cursor-adapter.d.ts

@@ -11,6 +11,9 @@ export declare class CursorAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Cursor is available in the project

package/dist/core/adapters/cursor-adapter.js

@@ -12,6 +12,7 @@ export class CursorAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: false,
         supportsFrontmatter: false,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Cursor is available in the project

package/dist/core/adapters/droid-adapter.d.ts

@@ -15,6 +15,9 @@ export declare class DroidAdapter extends BaseAdapter {
         supportsFrontmatter: boolean;
         frontmatterFields: string[];
         argumentPlaceholder: string;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Droid CLI is available in the project

package/dist/core/adapters/droid-adapter.js

@@ -15,6 +15,7 @@ export class DroidAdapter extends BaseAdapter {
         supportsFrontmatter: true,
         frontmatterFields: ['description', 'argument-hint'],
         argumentPlaceholder: '$ARGUMENTS',
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Droid CLI is available in the project

package/dist/core/adapters/instructions-generator.js

@@ -1,5 +1,6 @@
 import { FileSystem } from '../../utils/file-system.js';
 import { TemplateAssembler } from '../template-assembler.js';
+import { CommandTransformer } from '../command-transformer.js';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
@@ -79,17 +80,23 @@ export class InstructionsGenerator {
         // Copy all .md files from canonical, resolving includes
         const entries = await FileSystem.readdir(canonicalPath, { withFileTypes: true });
         const mdFiles = entries.filter((f) => f.isFile() && f.name.endsWith('.md'));
+        // v4.8.1: Generic integrations use hyphen format for slash commands
+        const genericFeatures = { commandFormat: { separator: '-' } };
         for (const file of mdFiles) {
             const destPath = path.join(workflowsTarget, file.name);
             try {
                 // v4.5: Use TemplateAssembler to resolve {{INCLUDE:}} markers
                 const result = await assembler.assembleTemplate(file.name);
-                await FileSystem.writeFileAtomic(destPath, result.content);
+                // v4.8.1: Transform command references to hyphen format for generic integrations
+                const transformedContent = CommandTransformer.transform(result.content, genericFeatures);
+                await FileSystem.writeFileAtomic(destPath, transformedContent);
             }
             catch {
                 // Fallback: copy without include resolution if assembly fails
                 const srcPath = path.join(canonicalPath, file.name);
-                const content = await FileSystem.readFile(srcPath);
+                let content = await FileSystem.readFile(srcPath);
+                // v4.8.1: Still transform command references in fallback path
+                content = CommandTransformer.transform(content, genericFeatures);
                 await FileSystem.writeFileAtomic(destPath, content);
             }
         }

package/dist/core/adapters/kilocode-adapter.d.ts

@@ -19,6 +19,9 @@ export declare class KilocodeAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Kilocode is available in the project

package/dist/core/adapters/kilocode-adapter.js

@@ -20,6 +20,7 @@ export class KilocodeAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: false,
         supportsFrontmatter: false,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Kilocode is available in the project

package/dist/core/adapters/opencode-adapter.d.ts

@@ -15,6 +15,9 @@ export declare class OpenCodeAdapter extends BaseAdapter {
         supportsFrontmatter: boolean;
         frontmatterFields: string[];
         argumentPlaceholder: string;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if OpenCode is available in the project

package/dist/core/adapters/opencode-adapter.js

@@ -15,6 +15,7 @@ export class OpenCodeAdapter extends BaseAdapter {
         supportsFrontmatter: true,
         frontmatterFields: ['description', 'agent', 'model'],
         argumentPlaceholder: '$ARGUMENTS',
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if OpenCode is available in the project

package/dist/core/adapters/roocode-adapter.d.ts

@@ -20,6 +20,9 @@ export declare class RoocodeAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Roocode is available in the project

package/dist/core/adapters/roocode-adapter.js

@@ -20,6 +20,7 @@ export class RoocodeAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: false,
         supportsFrontmatter: true,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Roocode is available in the project

package/dist/core/adapters/windsurf-adapter.d.ts

@@ -19,6 +19,9 @@ export declare class WindsurfAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
         supportsFrontmatter: boolean;
+        commandFormat: {
+            separator: "-";
+        };
     };
     /**
      * Detect if Windsurf is available in the project

package/dist/core/adapters/windsurf-adapter.js

@@ -20,6 +20,7 @@ export class WindsurfAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: true,
         supportsFrontmatter: false,
+        commandFormat: { separator: '-' },
     };
     /**
      * Detect if Windsurf is available in the project

package/dist/core/command-transformer.d.ts

@@ -0,0 +1,55 @@
+import { IntegrationFeatures } from '../types/agent.js';
+/**
+ * CommandTransformer - Transforms slash command references in template content
+ *
+ * Handles conversion between command formats:
+ * - Colon format: /clavix:fast (Claude Code style - uses subdirectories)
+ * - Hyphen format: /clavix-fast (Cursor, Droid style - flat files)
+ *
+ * Preserves CLI commands (clavix prompts list) unchanged - only transforms
+ * slash commands that start with /clavix:
+ *
+ * @since v4.8.1
+ */
+export declare class CommandTransformer {
+    /**
+     * Matches /clavix:commandname pattern
+     * Supports hyphenated commands like task-complete
+     * Does NOT match CLI usage (no leading slash)
+     */
+    private static readonly SLASH_COMMAND_PATTERN;
+    /** Default command format (canonical/Claude Code style) */
+    private static readonly DEFAULT_SEPARATOR;
+    /**
+     * Transform slash command references in content based on adapter's command format
+     *
+     * @param content - Template content with canonical /clavix:command references
+     * @param features - Adapter's integration features (may include commandFormat)
+     * @returns Transformed content with correct command format
+     *
+     * @example
+     * // For Cursor/Droid (hyphen format):
+     * transform('/clavix:fast', { commandFormat: { separator: '-' } })
+     * // Returns: '/clavix-fast'
+     *
+     * @example
+     * // For Claude Code (colon format, default):
+     * transform('/clavix:fast', { commandFormat: { separator: ':' } })
+     * // Returns: '/clavix:fast' (unchanged)
+     */
+    static transform(content: string, features?: IntegrationFeatures): string;
+    /**
+     * Get the formatted command name for a specific adapter
+     * Useful for generating documentation or references
+     *
+     * @param commandName - Base command name (e.g., 'fast', 'execute', 'task-complete')
+     * @param features - Adapter's integration features
+     * @returns Formatted slash command (e.g., '/clavix:fast' or '/clavix-fast')
+     *
+     * @example
+     * formatCommand('execute', { commandFormat: { separator: '-' } })
+     * // Returns: '/clavix-execute'
+     */
+    static formatCommand(commandName: string, features?: IntegrationFeatures): string;
+}
+//# sourceMappingURL=command-transformer.d.ts.map

package/dist/core/command-transformer.js

@@ -0,0 +1,65 @@
+/**
+ * CommandTransformer - Transforms slash command references in template content
+ *
+ * Handles conversion between command formats:
+ * - Colon format: /clavix:fast (Claude Code style - uses subdirectories)
+ * - Hyphen format: /clavix-fast (Cursor, Droid style - flat files)
+ *
+ * Preserves CLI commands (clavix prompts list) unchanged - only transforms
+ * slash commands that start with /clavix:
+ *
+ * @since v4.8.1
+ */
+export class CommandTransformer {
+    /**
+     * Matches /clavix:commandname pattern
+     * Supports hyphenated commands like task-complete
+     * Does NOT match CLI usage (no leading slash)
+     */
+    static SLASH_COMMAND_PATTERN = /\/clavix:(\w+(?:-\w+)*)/g;
+    /** Default command format (canonical/Claude Code style) */
+    static DEFAULT_SEPARATOR = ':';
+    /**
+     * Transform slash command references in content based on adapter's command format
+     *
+     * @param content - Template content with canonical /clavix:command references
+     * @param features - Adapter's integration features (may include commandFormat)
+     * @returns Transformed content with correct command format
+     *
+     * @example
+     * // For Cursor/Droid (hyphen format):
+     * transform('/clavix:fast', { commandFormat: { separator: '-' } })
+     * // Returns: '/clavix-fast'
+     *
+     * @example
+     * // For Claude Code (colon format, default):
+     * transform('/clavix:fast', { commandFormat: { separator: ':' } })
+     * // Returns: '/clavix:fast' (unchanged)
+     */
+    static transform(content, features) {
+        const separator = features?.commandFormat?.separator ?? this.DEFAULT_SEPARATOR;
+        // If using canonical format (colon), no transformation needed
+        if (separator === ':') {
+            return content;
+        }
+        // Transform /clavix:command to /clavix-command (or other separator)
+        return content.replace(this.SLASH_COMMAND_PATTERN, `/clavix${separator}$1`);
+    }
+    /**
+     * Get the formatted command name for a specific adapter
+     * Useful for generating documentation or references
+     *
+     * @param commandName - Base command name (e.g., 'fast', 'execute', 'task-complete')
+     * @param features - Adapter's integration features
+     * @returns Formatted slash command (e.g., '/clavix:fast' or '/clavix-fast')
+     *
+     * @example
+     * formatCommand('execute', { commandFormat: { separator: '-' } })
+     * // Returns: '/clavix-execute'
+     */
+    static formatCommand(commandName, features) {
+        const separator = features?.commandFormat?.separator ?? this.DEFAULT_SEPARATOR;
+        return `/clavix${separator}${commandName}`;
+    }
+}
+//# sourceMappingURL=command-transformer.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

@@ -207,30 +207,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
 
 ---
 
@@ -479,27 +484,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 +511,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