clavix 5.4.0 → 5.5.1

package/README.md

@@ -1,65 +1,27 @@
 # Clavix
-> 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.
-
-## Table of contents
-- [Why Clavix?](#why-clavix)
-- [How It Works](#how-it-works)
-- [Supported AI Tools](#supported-ai-tools)
-- [Quickstart](#quickstart)
-- [Full documentation](#full-documentation)
-
-## Release Notes
-
-| Version | Highlights | Details |
-| --- | --- | --- |
-| **v5.2.1** (Latest) | Diagnose command, DRY architecture, feature matrix | [Changelog](CHANGELOG.md) |
-| **v5.0.0** | Agentic-first architecture - lean template delivery | [Changelog](CHANGELOG.md#500---2025-01-27) |
-| **v4.12.0** | Final v4 release with full CLI commands | [Changelog](docs/archive/v4-changelog.md) |
-
-**Requirements:** Node.js >= 18.0.0
-
-## Why Clavix?
-
-Better prompts lead to better code. Clavix provides **markdown templates** that teach AI agents how to:
-- **Optimize prompts** - Transform rough ideas into structured, AI-ready prompts
-- **Create PRDs** - Generate comprehensive requirements documents through guided questions
-- **Plan implementations** - Break down PRDs into phased task lists
-- **Track progress** - Manage task completion with optional git commits
-
-**No framework to learn.** Just describe what you want, and your AI agent follows the Clavix templates to structure it properly.
-
-Learn more in [docs/why-clavix.md](docs/why-clavix.md).
 
-## How It Works
+> 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.
 
-Clavix v5 follows an **agentic-first architecture**:
+## Quick Links
 
-1. **You run `clavix init`** - Sets up `.clavix/` directory with slash command templates
-2. **You invoke a slash command** - Like `/clavix:improve` in Claude Code or Cursor
-3. **Your AI agent reads the template** - The markdown file contains all instructions
-4. **The agent follows the instructions** - Using its native tools (Write, Read, Edit, etc.)
-5. **Output is saved** - To `.clavix/outputs/` for future reference
+| I want to... | Go to |
+|--------------|-------|
+| Get started | [Quickstart](#quickstart) |
+| See all commands | [docs/commands.md](docs/commands.md) |
+| Understand the architecture | [docs/architecture.md](docs/architecture.md) |
+| Check integrations | [docs/integrations.md](docs/integrations.md) |
+| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
-**No TypeScript code executes during slash command usage.** The templates are the product - they instruct AI agents on what to do.
+## Command Format
 
-## Supported AI Tools
+**Your command format depends on your AI tool:**
 
-| Category | Tools |
-| --- | --- |
-| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
-| CLI agents | Claude Code, Droid CLI, CodeBuddy CLI, OpenCode, Gemini CLI, Qwen Code, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI |
-| Universal adapters | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
+| Tool Type | Format | Example |
+|-----------|--------|---------|
+| **CLI tools** (Claude Code, Gemini, Qwen) | Colon (`:`) | `/clavix:improve` |
+| **IDE extensions** (Cursor, Windsurf, Cline) | Hyphen (`-`) | `/clavix-improve` |
 
-### Feature Matrix
-
-| Feature | Claude Code | Cursor/Windsurf | Gemini/Qwen | Generic Agents |
-|---------|-------------|-----------------|-------------|----------------|
-| Slash commands | ✅ Native | ✅ Native | ✅ TOML | ❌ Read-only |
-| Doc injection | ✅ CLAUDE.md | ✅ .cursor/rules | ✅ N/A | ✅ AGENTS.md |
-| Namespace dirs | ✅ clavix/ | ✅ clavix/ | ✅ clavix/ | N/A |
-| Auto-detection | ✅ Yes | ✅ Yes | ✅ Yes | N/A |
-
-Full list and configuration: [docs/integrations.md](docs/integrations.md)
+**Rule of thumb:** CLI tools use colon, IDE extensions use hyphen.
 
 ## Quickstart
 
@@ -70,81 +32,76 @@ npm install -g clavix
 clavix init
 ```
 
-This creates `.clavix/` with slash command templates and injects documentation into your CLAUDE.md (or equivalent).
-
 ### 2. Use Slash Commands
 
-In your AI coding assistant (Claude Code, Cursor, etc.):
-
 ```
 /clavix:improve "Create a secure login page with JWT"
 ```
 
-The AI agent reads the improve template and:
-- Analyzes your prompt for quality
-- Applies optimization patterns
-- Saves the improved version to `.clavix/outputs/prompts/`
+The AI agent reads the template and optimizes your prompt.
 
 ### 3. Choose Your Workflow
 
-**Core Workflows:**
 | Command | When to Use |
 |---------|-------------|
-| `/clavix:improve` | Optimize a single prompt (auto-selects depth) |
+| `/clavix:improve` | Optimize a single prompt |
 | `/clavix:prd` | Plan something new with guided questions |
-| `/clavix:start` | Explore ideas conversationally first |
 | `/clavix:plan` | Generate tasks from a PRD |
 | `/clavix:implement` | Execute tasks with progress tracking |
-| `/clavix:summarize` | Extract requirements from conversation |
 
-**Project Management:**
-| Utility | Purpose |
-|---------|---------|
-| `/clavix:verify` | Check implementation against PRD requirements |
-| `/clavix:archive` | Archive completed projects to `.clavix/archive/` |
+See [Getting Started](docs/getting-started.md) for the full guide.
 
-See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
+## How It Works
 
-### 4. Keep Templates Updated
+Clavix is **agentic-first**:
 
-```bash
-clavix update   # After npm update clavix
-```
+1. **You run `clavix init`** - Sets up slash command templates
+2. **You invoke a slash command** - Like `/clavix:improve`
+3. **AI agent reads the template** - Markdown instructions
+4. **Agent follows instructions** - Using its native tools
+5. **Output is saved** - To `.clavix/outputs/`
 
-## CLI Commands
+**No TypeScript executes during slash commands.** The markdown templates ARE the product.
 
-Clavix v5 has 4 CLI commands (for setup and diagnostics, not workflows):
+See [Architecture](docs/architecture.md) for details.
+
+## Supported AI Tools
+
+| Category | Tools |
+|----------|-------|
+| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
+| CLI agents | Claude Code, Gemini CLI, Qwen Code, Droid CLI, CodeBuddy, OpenCode, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI |
+| Universal | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
+
+Full list: [docs/integrations.md](docs/integrations.md)
+
+## CLI Commands
 
 | Command | Purpose |
 |---------|---------|
-| `clavix init` | Initialize or reconfigure Clavix in a project |
-| `clavix update` | Update templates after package update |
-| `clavix diagnose` | Check installation and report issues |
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Regenerate templates |
+| `clavix diagnose` | Check installation |
 | `clavix version` | Show version |
 
-**All workflows** (`/clavix:improve`, `/clavix:prd`, etc.) are **slash commands** that AI agents execute by reading markdown templates.
+All workflows (`/clavix:improve`, etc.) are **slash commands** that AI agents execute.
 
-## Full documentation
-- Overview & navigation: [docs/README.md](docs/README.md)
-- Integrations: [docs/integrations.md](docs/integrations.md)
-- How it works: [docs/how-it-works.md](docs/how-it-works.md)
-- Philosophy: [docs/philosophy.md](docs/philosophy.md)
-- v4 Architecture (archived): [docs/archive/v4-architecture.md](docs/archive/v4-architecture.md)
+## Documentation
 
-## Requirements
+- [Getting Started](docs/getting-started.md) - Installation and first workflow
+- [Commands Reference](docs/commands.md) - All commands in one place
+- [Architecture](docs/architecture.md) - How Clavix works
+- [Integrations](docs/integrations.md) - Full tool matrix
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribute to Clavix
 
-### For End Users
-- **Node.js >= 18.0.0**
-- npm or yarn package manager
-- An AI coding assistant (Claude Code, Cursor, Windsurf, etc.)
+## Requirements
 
-### For Contributors
 - **Node.js >= 18.0.0**
-- Run tests: `npm test`
-- Lint: `npm run lint`
-- Build: `npm run build`
+- npm or yarn
+- An AI coding tool (Claude Code, Cursor, etc.)
 
 ## License
+
 Apache-2.0
 
 ## Star History

package/dist/cli/commands/init.js

@@ -272,18 +272,30 @@ export default class Init extends Command {
                 await InstructionsGenerator.generate();
                 console.log(chalk.gray('  ✓ Created detailed workflow guides for generic integrations'));
             }
-            // Success message
-            // v4.11: Use generic command names - format varies by integration
-            // (claude-code uses colon like /clavix:improve, droid uses hyphen like /clavix-improve)
+            // Success message with prominent command format display
             console.log(chalk.bold.green('\n✅ Clavix initialized successfully!\n'));
-            console.log(chalk.gray('Next steps:'));
+            // Determine the primary command format based on selected integrations
+            const colonTools = ['claude-code', 'gemini', 'qwen', 'crush', 'llxprt', 'augment'];
+            const usesColon = selectedIntegrations.some((i) => colonTools.includes(i));
+            const usesHyphen = selectedIntegrations.some((i) => !colonTools.includes(i));
+            const separator = usesColon && !usesHyphen ? ':' : usesHyphen && !usesColon ? '-' : ':';
+            const altSeparator = separator === ':' ? '-' : ':';
+            // Show command format prominently at the TOP
+            console.log(chalk.bold('📋 Your command format:'), chalk.bold.cyan(`/clavix${separator}improve`));
+            if (usesColon && usesHyphen) {
+                console.log(chalk.gray('   (Some integrations use'), chalk.cyan(`/clavix${altSeparator}improve`), chalk.gray('instead)'));
+            }
+            console.log();
+            // Available commands
+            console.log(chalk.gray('Available slash commands:'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}improve`), chalk.gray('- Smart prompt optimization'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}prd`), chalk.gray('- Generate PRD through guided questions'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}plan`), chalk.gray('- Create task breakdown from PRD'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}implement`), chalk.gray('- Execute tasks or prompts'));
+            console.log(chalk.gray('\nNext steps:'));
             console.log(chalk.gray('  • Slash commands are now available in your AI agent'));
-            console.log(chalk.gray('  • Run'), chalk.cyan('clavix --help'), chalk.gray('to see all CLI commands'));
-            console.log(chalk.gray('  • Available slash commands:'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('improve'), chalk.gray('- Smart prompt optimization with auto depth selection'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('prd'), chalk.gray('- Generate PRD through guided questions'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('execute'), chalk.gray('- Run saved prompts'));
-            console.log(chalk.gray('\n  Command format varies by integration (colon vs hyphen)\n'));
+            console.log(chalk.gray('  • Run'), chalk.cyan('clavix diagnose'), chalk.gray('to verify installation'));
+            console.log();
         }
         catch (error) {
             const { getErrorMessage, toError } = await import('../../utils/error-utils.js');
@@ -378,6 +390,17 @@ export default class Init extends Command {
 
 Welcome to Clavix! This directory contains your local Clavix configuration and data.
 
+## Command Format
+
+**Your command format depends on your AI tool:**
+
+| Tool Type | Format | Example |
+|-----------|--------|---------|
+| **CLI tools** (Claude Code, Gemini, Qwen) | Colon (\`:\`) | \`/clavix:improve\` |
+| **IDE extensions** (Cursor, Windsurf, Cline) | Hyphen (\`-\`) | \`/clavix-improve\` |
+
+**Rule of thumb:** CLI tools use colon, IDE extensions use hyphen.
+
 ## Directory Structure
 
 \`\`\`

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

@@ -50,10 +50,5 @@ export declare abstract class BaseAdapter implements AgentAdapter {
      * Override if integration needs doc injection (like Claude Code)
      */
     injectDocumentation(_blocks: ManagedBlock[]): Promise<void>;
-    /**
-     * Escape special regex characters
-     * @deprecated Use escapeRegex from utils/string-utils.js directly
-     */
-    protected escapeRegex(str: string): string;
 }
 //# sourceMappingURL=base-adapter.d.ts.map

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

@@ -1,7 +1,7 @@
 import * as path from 'path';
 import { FileSystem } from '../../utils/file-system.js';
 import { IntegrationError } from '../../types/errors.js';
-import { escapeRegex } from '../../utils/string-utils.js';
+import { logger } from '../../utils/logger.js';
 /**
  * Base adapter class with shared logic for all integrations
  * Ensures consistency and reduces code duplication
@@ -82,7 +82,7 @@ export class BaseAdapter {
             }
             catch (error) {
                 // Log warning but continue with other files
-                console.warn(`Failed to remove ${filePath}: ${error}`);
+                logger.warn(`Failed to remove ${filePath}: ${error}`);
             }
         }
         // Also remove clavix/ subdirectory if it exists (legacy cleanup)
@@ -93,7 +93,7 @@ export class BaseAdapter {
                 removed++;
             }
             catch (error) {
-                console.warn(`Failed to remove ${clavixSubdir}: ${error}`);
+                logger.warn(`Failed to remove ${clavixSubdir}: ${error}`);
             }
         }
         return removed;
@@ -145,12 +145,5 @@ export class BaseAdapter {
         // Default: no documentation injection
         // Override in subclasses if needed
     }
-    /**
-     * Escape special regex characters
-     * @deprecated Use escapeRegex from utils/string-utils.js directly
-     */
-    escapeRegex(str) {
-        return escapeRegex(str);
-    }
 }
 //# sourceMappingURL=base-adapter.js.map

package/dist/core/adapters/claude-code-adapter.js

@@ -2,6 +2,7 @@ import * as path from 'path';
 import { BaseAdapter } from './base-adapter.js';
 import { FileSystem } from '../../utils/file-system.js';
 import { IntegrationError } from '../../types/errors.js';
+import { escapeRegex } from '../../utils/string-utils.js';
 /**
  * Claude Code agent adapter
  */
@@ -65,7 +66,7 @@ export class ClaudeCodeAdapter extends BaseAdapter {
             const dir = path.dirname(fullPath);
             await FileSystem.ensureDir(dir);
         }
-        const blockRegex = new RegExp(`${this.escapeRegex(startMarker)}[\\s\\S]*?${this.escapeRegex(endMarker)}`, 'g');
+        const blockRegex = new RegExp(`${escapeRegex(startMarker)}[\\s\\S]*?${escapeRegex(endMarker)}`, 'g');
         const wrappedContent = `${startMarker}\n${content}\n${endMarker}`;
         if (blockRegex.test(fileContent)) {
             // Replace existing block

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

@@ -15,6 +15,7 @@ import { AdapterConfig } from '../../types/adapter-config.js';
 import { IntegrationFeatures } from '../../types/agent.js';
 export declare class UniversalAdapter extends BaseAdapter {
     private config;
+    readonly features: IntegrationFeatures;
     constructor(config: AdapterConfig);
     get name(): string;
     get displayName(): string;

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

@@ -14,9 +14,18 @@ import { BaseAdapter } from './base-adapter.js';
 import * as path from 'path';
 export class UniversalAdapter extends BaseAdapter {
     config;
+    features;
     constructor(config) {
         super();
         this.config = config;
+        // Set features from config for interface compatibility
+        this.features = {
+            supportsSubdirectories: config.features.supportsSubdirectories,
+            supportsFrontmatter: config.features.supportsFrontmatter,
+            commandFormat: {
+                separator: config.features.commandSeparator,
+            },
+        };
     }
     get name() {
         return this.config.name;

package/dist/core/agent-manager.d.ts

@@ -1,6 +1,11 @@
 import { AgentAdapter, ValidationResult } from '../types/agent.js';
 /**
  * Agent Manager - handles agent detection and registration
+ *
+ * Uses factory pattern with ADAPTER_CONFIGS for simple adapters,
+ * while keeping dedicated classes for special adapters (TOML, doc injection).
+ *
+ * @since v5.5.0 - Refactored to use config-driven factory pattern
  */
 export declare class AgentManager {
     private adapters;

package/dist/core/agent-manager.js

@@ -1,43 +1,33 @@
 import { ClaudeCodeAdapter } from './adapters/claude-code-adapter.js';
-import { CursorAdapter } from './adapters/cursor-adapter.js';
-import { DroidAdapter } from './adapters/droid-adapter.js';
-import { OpenCodeAdapter } from './adapters/opencode-adapter.js';
-import { AmpAdapter } from './adapters/amp-adapter.js';
-import { CrushAdapter } from './adapters/crush-adapter.js';
-import { WindsurfAdapter } from './adapters/windsurf-adapter.js';
-import { KilocodeAdapter } from './adapters/kilocode-adapter.js';
-import { ClineAdapter } from './adapters/cline-adapter.js';
-import { RoocodeAdapter } from './adapters/roocode-adapter.js';
-import { IntegrationError } from '../types/errors.js';
-import { CodeBuddyAdapter } from './adapters/codebuddy-adapter.js';
 import { GeminiAdapter } from './adapters/gemini-adapter.js';
 import { QwenAdapter } from './adapters/qwen-adapter.js';
-import { CodexAdapter } from './adapters/codex-adapter.js';
-import { AugmentAdapter } from './adapters/augment-adapter.js';
 import { LlxprtAdapter } from './adapters/llxprt-adapter.js';
+import { UniversalAdapter } from './adapters/universal-adapter.js';
+import { getSimpleAdapters } from './adapter-registry.js';
+import { IntegrationError } from '../types/errors.js';
 /**
  * Agent Manager - handles agent detection and registration
+ *
+ * Uses factory pattern with ADAPTER_CONFIGS for simple adapters,
+ * while keeping dedicated classes for special adapters (TOML, doc injection).
+ *
+ * @since v5.5.0 - Refactored to use config-driven factory pattern
  */
 export class AgentManager {
     adapters = new Map();
     constructor() {
-        // Register all built-in adapters
-        this.registerAdapter(new ClaudeCodeAdapter());
-        this.registerAdapter(new CursorAdapter());
-        this.registerAdapter(new DroidAdapter());
-        this.registerAdapter(new OpenCodeAdapter());
-        this.registerAdapter(new AmpAdapter());
-        this.registerAdapter(new CrushAdapter());
-        this.registerAdapter(new WindsurfAdapter());
-        this.registerAdapter(new KilocodeAdapter());
-        this.registerAdapter(new LlxprtAdapter());
-        this.registerAdapter(new ClineAdapter());
-        this.registerAdapter(new RoocodeAdapter());
-        this.registerAdapter(new AugmentAdapter());
-        this.registerAdapter(new CodeBuddyAdapter());
-        this.registerAdapter(new GeminiAdapter());
-        this.registerAdapter(new QwenAdapter());
-        this.registerAdapter(new CodexAdapter());
+        // Register special adapters (require custom logic)
+        this.registerAdapter(new ClaudeCodeAdapter()); // Doc injection
+        this.registerAdapter(new GeminiAdapter()); // TOML format
+        this.registerAdapter(new QwenAdapter()); // TOML format
+        this.registerAdapter(new LlxprtAdapter()); // TOML format
+        // Register simple adapters from config (using UniversalAdapter factory)
+        for (const config of getSimpleAdapters()) {
+            // Skip adapters that have special handlers registered above
+            if (this.adapters.has(config.name))
+                continue;
+            this.registerAdapter(new UniversalAdapter(config));
+        }
     }
     /**
      * Register a new agent adapter

package/dist/core/doc-injector.js

@@ -2,6 +2,7 @@ import * as path from 'path';
 import { FileSystem } from '../utils/file-system.js';
 import { DataError } from '../types/errors.js';
 import { escapeRegex } from '../utils/string-utils.js';
+import { logger } from '../utils/logger.js';
 /**
  * DocInjector - manages injection and updating of managed blocks in documentation files
  */
@@ -124,7 +125,7 @@ export class DocInjector {
         const openBrackets = (content.match(/\[/g) || []).length;
         const closeBrackets = (content.match(/\]/g) || []).length;
         if (openBrackets !== closeBrackets) {
-            console.warn('Warning: Unbalanced brackets in markdown');
+            logger.warn('Unbalanced brackets in markdown');
         }
     }
     /**

package/dist/utils/template-loader.js

@@ -4,6 +4,7 @@ import { dirname } from 'path';
 import { FileSystem } from './file-system.js';
 import { TemplateAssembler } from '../core/template-assembler.js';
 import { CommandTransformer } from '../core/command-transformer.js';
+import { DataError } from '../types/errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // v4.0: Singleton assembler instance for caching
@@ -39,8 +40,8 @@ export async function loadCommandTemplates(adapter) {
                 content = result.content;
             }
             catch (error) {
-                // If assembly fails, use original content
-                console.warn(`Template assembly warning for ${file}:`, error);
+                // Template assembly failures are critical - throw typed error
+                throw new DataError(`Template assembly failed for ${file}: ${error}`, `Check that all {{INCLUDE:}} references exist in templates directory`);
             }
         }
         // v4.8.1: Transform command references based on adapter format

package/oclif.manifest.json

@@ -126,5 +126,5 @@
       ]
     }
   },
-  "version": "5.4.0"
+  "version": "5.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.4.0",
+  "version": "5.5.1",
   "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation.\n\nSLASH COMMANDS (in your AI assistant):\n  /clavix:improve    Optimize prompts with auto-depth\n  /clavix:prd        Generate PRD through questions\n  /clavix:plan       Create task breakdown from PRD\n  /clavix:implement  Execute tasks with progress tracking\n  /clavix:start      Begin conversational session\n  /clavix:summarize  Extract requirements from conversation\n\nWorks with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",