clavix 5.6.4 → 5.6.6

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+> 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 20 AI coding tools.
 
 ## Quick Links
 

package/dist/cli/commands/update.js

@@ -36,6 +36,12 @@ export default class Update extends Command {
     };
     async run() {
         const { flags } = await this.parse(Update);
+        // Validate flag combinations
+        if (flags['docs-only'] && flags['commands-only']) {
+            this.error(chalk.red('Cannot use --docs-only and --commands-only together.') +
+                '\n' +
+                chalk.yellow('Hint: Use one flag or neither (to update both).'));
+        }
         const clavixDir = path.join(process.cwd(), '.clavix');
         const configPath = path.join(clavixDir, 'config.json');
         if (!fs.existsSync(clavixDir) || !fs.existsSync(configPath)) {

package/dist/cli/helpers/init/commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Slash command generation for Clavix initialization
+ */
+import type { AgentAdapter, CommandTemplate } from '../../../types/agent.js';
+/**
+ * Generate slash commands for an adapter
+ * Returns the generated templates
+ */
+export declare function generateSlashCommands(adapter: AgentAdapter): Promise<CommandTemplate[]>;
+/**
+ * Collect and optionally remove legacy command files
+ * Returns paths of legacy files found
+ */
+export declare function collectLegacyFiles(adapter: AgentAdapter, templates: CommandTemplate[]): Promise<string[]>;
+/**
+ * Remove legacy command files
+ */
+export declare function removeLegacyFiles(files: string[]): Promise<void>;
+/**
+ * Get relative paths for legacy files (for display)
+ */
+export declare function getLegacyRelativePaths(files: string[]): string[];
+//# sourceMappingURL=commands.d.ts.map

package/dist/cli/helpers/init/commands.js

@@ -0,0 +1,39 @@
+/**
+ * Slash command generation for Clavix initialization
+ */
+import * as path from 'path';
+import { FileSystem } from '../../../utils/file-system.js';
+import { loadCommandTemplates } from '../../../utils/template-loader.js';
+import { collectLegacyCommandFiles } from '../../../utils/legacy-command-cleanup.js';
+/**
+ * Generate slash commands for an adapter
+ * Returns the generated templates
+ */
+export async function generateSlashCommands(adapter) {
+    const templates = await loadCommandTemplates(adapter);
+    await adapter.generateCommands(templates);
+    return templates;
+}
+/**
+ * Collect and optionally remove legacy command files
+ * Returns paths of legacy files found
+ */
+export async function collectLegacyFiles(adapter, templates) {
+    const commandNames = templates.map((template) => template.name);
+    return collectLegacyCommandFiles(adapter, commandNames);
+}
+/**
+ * Remove legacy command files
+ */
+export async function removeLegacyFiles(files) {
+    for (const file of files) {
+        await FileSystem.remove(file);
+    }
+}
+/**
+ * Get relative paths for legacy files (for display)
+ */
+export function getLegacyRelativePaths(files) {
+    return files.map((file) => path.relative(process.cwd(), file)).sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=commands.js.map

package/dist/cli/helpers/init/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Configuration generation and management for Clavix initialization
+ */
+/**
+ * Load existing config if present
+ * Returns null if no config exists or parsing fails
+ */
+export declare function loadExistingConfig(): Promise<{
+    integrations: string[];
+    warnings?: string[];
+} | null>;
+/**
+ * Generate and save the Clavix config file
+ */
+export declare function generateConfig(integrations: string[]): Promise<void>;
+/**
+ * Check if Clavix is already initialized in the current directory
+ */
+export declare function isInitialized(): Promise<boolean>;
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/helpers/init/config.js

@@ -0,0 +1,49 @@
+/**
+ * Configuration generation and management for Clavix initialization
+ */
+import { FileSystem } from '../../../utils/file-system.js';
+import { DEFAULT_CONFIG } from '../../../types/config.js';
+import { validateUserConfig } from '../../../utils/schemas.js';
+/**
+ * Load existing config if present
+ * Returns null if no config exists or parsing fails
+ */
+export async function loadExistingConfig() {
+    if (!(await FileSystem.exists('.clavix/config.json'))) {
+        return null;
+    }
+    try {
+        const configContent = await FileSystem.readFile('.clavix/config.json');
+        const rawConfig = JSON.parse(configContent);
+        const validationResult = validateUserConfig(rawConfig);
+        if (validationResult.success && validationResult.data) {
+            return {
+                integrations: validationResult.data.integrations || validationResult.data.providers || [],
+                warnings: validationResult.warnings,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generate and save the Clavix config file
+ */
+export async function generateConfig(integrations) {
+    const config = {
+        ...DEFAULT_CONFIG,
+        integrations,
+    };
+    const configPath = '.clavix/config.json';
+    const configContent = JSON.stringify(config, null, 2);
+    await FileSystem.writeFileAtomic(configPath, configContent);
+}
+/**
+ * Check if Clavix is already initialized in the current directory
+ */
+export async function isInitialized() {
+    return FileSystem.exists('.clavix');
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/helpers/init/directories.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Directory structure creation for Clavix initialization
+ */
+/**
+ * Standard Clavix directory structure
+ */
+export declare const CLAVIX_DIRECTORIES: readonly [".clavix", ".clavix/outputs", ".clavix/templates"];
+/**
+ * Create the standard Clavix directory structure
+ */
+export declare function createDirectoryStructure(): Promise<void>;
+//# sourceMappingURL=directories.d.ts.map

package/dist/cli/helpers/init/directories.js

@@ -0,0 +1,17 @@
+/**
+ * Directory structure creation for Clavix initialization
+ */
+import { FileSystem } from '../../../utils/file-system.js';
+/**
+ * Standard Clavix directory structure
+ */
+export const CLAVIX_DIRECTORIES = ['.clavix', '.clavix/outputs', '.clavix/templates'];
+/**
+ * Create the standard Clavix directory structure
+ */
+export async function createDirectoryStructure() {
+    for (const dir of CLAVIX_DIRECTORIES) {
+        await FileSystem.ensureDir(dir);
+    }
+}
+//# sourceMappingURL=directories.js.map

package/dist/cli/helpers/init/documentation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Documentation generation and injection for Clavix initialization
+ */
+import type { AgentAdapter } from '../../../types/agent.js';
+/**
+ * Extract the Clavix block content from a full document
+ */
+export declare function extractClavixBlock(content: string): string;
+/**
+ * Inject documentation blocks for an adapter
+ */
+export declare function injectDocumentation(adapter: AgentAdapter): Promise<void>;
+/**
+ * Generate the INSTRUCTIONS.md file content
+ */
+export declare function getInstructionsContent(): string;
+/**
+ * Generate the INSTRUCTIONS.md file
+ */
+export declare function generateInstructions(): Promise<void>;
+/**
+ * Generate the QUICKSTART.md file
+ */
+export declare function generateQuickstart(): Promise<void>;
+//# sourceMappingURL=documentation.d.ts.map

package/dist/cli/helpers/init/documentation.js

@@ -0,0 +1,176 @@
+/**
+ * Documentation generation and injection for Clavix initialization
+ */
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { FileSystem } from '../../../utils/file-system.js';
+import { DocInjector } from '../../../core/doc-injector.js';
+import { CLAVIX_BLOCK_START, CLAVIX_BLOCK_END } from '../../../constants.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Extract the Clavix block content from a full document
+ */
+export function extractClavixBlock(content) {
+    const regex = new RegExp(`${CLAVIX_BLOCK_START}([\\s\\S]*?)${CLAVIX_BLOCK_END}`);
+    const match = content.match(regex);
+    return match ? match[1].trim() : content;
+}
+/**
+ * Inject documentation blocks for an adapter
+ */
+export async function injectDocumentation(adapter) {
+    // Inject AGENTS.md
+    const agentsContent = DocInjector.getDefaultAgentsContent();
+    await DocInjector.injectBlock('AGENTS.md', extractClavixBlock(agentsContent));
+    // Inject CLAUDE.md if Claude Code selected
+    if (adapter.name === 'claude-code') {
+        const claudeContent = DocInjector.getDefaultClaudeContent();
+        await DocInjector.injectBlock('CLAUDE.md', extractClavixBlock(claudeContent));
+    }
+}
+/**
+ * Generate the INSTRUCTIONS.md file content
+ */
+export function getInstructionsContent() {
+    return `# Clavix Instructions
+
+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
+
+\`\`\`
+.clavix/
+├── config.json           # Your Clavix configuration
+├── INSTRUCTIONS.md       # This file
+├── instructions/         # Workflow instruction files for AI agents
+├── outputs/
+│   ├── <project-name>/  # Per-project outputs
+│   │   ├── full-prd.md
+│   │   ├── quick-prd.md
+│   │   └── tasks.md
+│   ├── prompts/         # Saved prompts for re-execution
+│   └── archive/         # Archived completed projects
+└── templates/           # Custom template overrides (optional)
+\`\`\`
+
+## Clavix Commands (v5)
+
+### Setup Commands (CLI)
+
+| Command | Purpose |
+|---------|---------|
+| \`clavix init\` | Initialize Clavix in a project |
+| \`clavix update\` | Update templates after package update |
+| \`clavix diagnose\` | Check installation health |
+| \`clavix version\` | Show version |
+
+### Workflow Commands (Slash Commands)
+
+All workflows are executed via slash commands that AI agents read and follow:
+
+| Slash Command | Purpose |
+|---------------|---------|
+| \`/clavix:improve\` | Optimize prompts (auto-selects depth) |
+| \`/clavix:prd\` | Generate PRD through guided questions |
+| \`/clavix:plan\` | Create task breakdown from PRD |
+| \`/clavix:implement\` | Execute tasks or prompts (auto-detects source) |
+| \`/clavix:start\` | Begin conversational session |
+| \`/clavix:summarize\` | Extract requirements from conversation |
+| \`/clavix:verify\` | Verify implementation |
+| \`/clavix:archive\` | Archive completed projects |
+
+**Note:** Running \`clavix init\` or \`clavix update\` will regenerate all slash commands from templates. Any manual edits to generated commands will be lost. If you need custom commands, create new command files instead of modifying generated ones.
+
+**Command format varies by integration:**
+- Claude Code, Gemini, Qwen: \`/clavix:improve\` (colon format)
+- Cursor, Droid, Windsurf, etc.: \`/clavix-improve\` (hyphen format)
+
+## Standard Workflow
+
+**Clavix follows this progression:**
+
+\`\`\`
+PRD Creation → Task Planning → Implementation → Archive
+\`\`\`
+
+**Detailed steps:**
+
+1. **Planning Phase**
+   - Run: \`/clavix:prd\` or \`/clavix:start\` → \`/clavix:summarize\`
+   - Output: \`.clavix/outputs/{project}/full-prd.md\` + \`quick-prd.md\`
+
+2. **Task Preparation**
+   - Run: \`/clavix:plan\` transforms PRD into curated task list
+   - Output: \`.clavix/outputs/{project}/tasks.md\`
+
+3. **Implementation Phase**
+   - Run: \`/clavix:implement\`
+   - Agent executes tasks systematically
+   - Agent edits tasks.md directly to mark progress (\`- [ ]\` → \`- [x]\`)
+
+4. **Completion**
+   - Run: \`/clavix:archive\`
+   - Archives completed work
+
+**Key principle:** Planning workflows create documents. Implementation workflows write code.
+
+## Prompt Lifecycle
+
+1. **Optimize prompt**: \`/clavix:improve\` - Analyzes and improves your prompt
+2. **Review**: Agent lists saved prompts from \`.clavix/outputs/prompts/\`
+3. **Execute**: \`/clavix:implement --latest\` - Implement when ready
+4. **Cleanup**: Agent deletes old prompt files from \`.clavix/outputs/prompts/\`
+
+## When to Use Which Mode
+
+- **Improve mode** (\`/clavix:improve\`): Smart prompt optimization with auto-depth selection
+- **PRD mode** (\`/clavix:prd\`): Strategic planning with architecture and business impact
+- **Conversational mode** (\`/clavix:start\` → \`/clavix:summarize\`): Natural discussion → extract structured requirements
+
+## Customization
+
+Create custom templates in \`.clavix/templates/\` to override defaults.
+
+To reconfigure integrations, run \`clavix init\` again.
+
+## Need Help?
+
+- **Documentation**: https://github.com/ClavixDev/Clavix
+- **Issues**: https://github.com/ClavixDev/Clavix/issues
+- **Version**: Run \`clavix version\` to check your installed version
+- **Update managed blocks**: Run \`clavix update\` to refresh documentation
+`;
+}
+/**
+ * Generate the INSTRUCTIONS.md file
+ */
+export async function generateInstructions() {
+    await FileSystem.writeFileAtomic('.clavix/INSTRUCTIONS.md', getInstructionsContent());
+}
+/**
+ * Generate the QUICKSTART.md file
+ */
+export async function generateQuickstart() {
+    const quickstartPath = path.join(__dirname, '..', '..', '..', 'templates', 'instructions', 'QUICKSTART.md');
+    try {
+        const quickstartContent = await FileSystem.readFile(quickstartPath);
+        await FileSystem.writeFileAtomic('.clavix/QUICKSTART.md', quickstartContent);
+    }
+    catch {
+        // QUICKSTART.md template not found or write failed, skip silently
+        // This can happen in test environments or custom installations
+    }
+}
+//# sourceMappingURL=documentation.js.map

package/dist/cli/helpers/init/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Init command modules
+ *
+ * This directory contains extracted modules from the init command,
+ * organized by responsibility:
+ *
+ * - config.ts: Configuration management
+ * - directories.ts: Directory structure creation
+ * - documentation.ts: Documentation generation
+ * - commands.ts: Slash command generation
+ * - integrations.ts: Integration handling
+ * - prompts.ts: User prompts
+ */
+export * from './config.js';
+export * from './directories.js';
+export * from './documentation.js';
+export * from './commands.js';
+export * from './integrations.js';
+export * from './prompts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/helpers/init/index.js

@@ -0,0 +1,20 @@
+/**
+ * Init command modules
+ *
+ * This directory contains extracted modules from the init command,
+ * organized by responsibility:
+ *
+ * - config.ts: Configuration management
+ * - directories.ts: Directory structure creation
+ * - documentation.ts: Documentation generation
+ * - commands.ts: Slash command generation
+ * - integrations.ts: Integration handling
+ * - prompts.ts: User prompts
+ */
+export * from './config.js';
+export * from './directories.js';
+export * from './documentation.js';
+export * from './commands.js';
+export * from './integrations.js';
+export * from './prompts.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/helpers/init/integrations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Integration handling for Clavix initialization
+ */
+import type { AgentManager } from '../../../core/agent-manager.js';
+/**
+ * Doc generator integrations (not regular adapters)
+ */
+export declare const DOC_GENERATOR_INTEGRATIONS: readonly ["agents-md", "octo-md", "warp-md", "copilot-instructions"];
+/**
+ * Integrations that use colon separator (CLI tools)
+ */
+export declare const COLON_SEPARATOR_INTEGRATIONS: readonly ["claude-code", "gemini", "qwen", "crush", "llxprt", "augment"];
+/**
+ * Check if an integration is a doc generator (not a regular adapter)
+ */
+export declare function isDocGeneratorIntegration(integrationName: string): boolean;
+/**
+ * Generate content for a doc generator integration
+ */
+export declare function generateDocGeneratorContent(integrationName: string): Promise<void>;
+/**
+ * Clean up a doc generator integration
+ */
+export declare function cleanupDocGeneratorIntegration(integrationName: string): Promise<void>;
+/**
+ * Check if instructions folder generation is needed
+ */
+export declare function needsInstructionsGeneration(integrations: string[]): boolean;
+/**
+ * Generate the instructions folder
+ */
+export declare function generateInstructionsFolder(): Promise<void>;
+/**
+ * Get display names for integrations
+ */
+export declare function getDisplayNames(agentManager: AgentManager, integrations: string[]): string[];
+/**
+ * Determine the command separator based on selected integrations
+ */
+export declare function determineCommandSeparator(integrations: string[]): {
+    primary: string;
+    alternate?: string;
+};
+//# sourceMappingURL=integrations.d.ts.map

package/dist/cli/helpers/init/integrations.js

@@ -0,0 +1,109 @@
+/**
+ * Integration handling for Clavix initialization
+ */
+import { DocInjector } from '../../../core/doc-injector.js';
+import { AgentsMdGenerator } from '../../../core/adapters/agents-md-generator.js';
+import { OctoMdGenerator } from '../../../core/adapters/octo-md-generator.js';
+import { WarpMdGenerator } from '../../../core/adapters/warp-md-generator.js';
+import { CopilotInstructionsGenerator } from '../../../core/adapters/copilot-instructions-generator.js';
+import { InstructionsGenerator } from '../../../core/adapters/instructions-generator.js';
+/**
+ * Doc generator integrations (not regular adapters)
+ */
+export const DOC_GENERATOR_INTEGRATIONS = [
+    'agents-md',
+    'octo-md',
+    'warp-md',
+    'copilot-instructions',
+];
+/**
+ * Integrations that use colon separator (CLI tools)
+ */
+export const COLON_SEPARATOR_INTEGRATIONS = [
+    'claude-code',
+    'gemini',
+    'qwen',
+    'crush',
+    'llxprt',
+    'augment',
+];
+/**
+ * Check if an integration is a doc generator (not a regular adapter)
+ */
+export function isDocGeneratorIntegration(integrationName) {
+    return DOC_GENERATOR_INTEGRATIONS.includes(integrationName);
+}
+/**
+ * Generate content for a doc generator integration
+ */
+export async function generateDocGeneratorContent(integrationName) {
+    switch (integrationName) {
+        case 'agents-md':
+            await AgentsMdGenerator.generate();
+            break;
+        case 'octo-md':
+            await OctoMdGenerator.generate();
+            break;
+        case 'warp-md':
+            await WarpMdGenerator.generate();
+            break;
+        case 'copilot-instructions':
+            await CopilotInstructionsGenerator.generate();
+            break;
+    }
+}
+/**
+ * Clean up a doc generator integration
+ */
+export async function cleanupDocGeneratorIntegration(integrationName) {
+    switch (integrationName) {
+        case 'agents-md':
+            await DocInjector.removeBlock('AGENTS.md');
+            break;
+        case 'octo-md':
+            await DocInjector.removeBlock('OCTO.md');
+            break;
+        case 'warp-md':
+            await DocInjector.removeBlock('WARP.md');
+            break;
+        case 'copilot-instructions':
+            await DocInjector.removeBlock('.github/copilot-instructions.md');
+            break;
+    }
+}
+/**
+ * Check if instructions folder generation is needed
+ */
+export function needsInstructionsGeneration(integrations) {
+    return InstructionsGenerator.needsGeneration(integrations);
+}
+/**
+ * Generate the instructions folder
+ */
+export async function generateInstructionsFolder() {
+    await InstructionsGenerator.generate();
+}
+/**
+ * Get display names for integrations
+ */
+export function getDisplayNames(agentManager, integrations) {
+    return integrations.map((name) => {
+        const adapter = agentManager.getAdapter(name);
+        return adapter?.displayName || name;
+    });
+}
+/**
+ * Determine the command separator based on selected integrations
+ */
+export function determineCommandSeparator(integrations) {
+    const usesColon = integrations.some((i) => COLON_SEPARATOR_INTEGRATIONS.includes(i));
+    const usesHyphen = integrations.some((i) => !COLON_SEPARATOR_INTEGRATIONS.includes(i));
+    if (usesColon && !usesHyphen) {
+        return { primary: ':' };
+    }
+    if (usesHyphen && !usesColon) {
+        return { primary: '-' };
+    }
+    return { primary: ':', alternate: '-' };
+}
+//# sourceMappingURL=integrations.js.map

package/dist/cli/helpers/init/prompts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Inquirer prompts for Clavix initialization
+ */
+import type { AgentAdapter } from '../../../types/agent.js';
+export type InitAction = 'reconfigure' | 'update' | 'cancel';
+export type CleanupAction = 'cleanup' | 'update' | 'skip';
+/**
+ * Prompt for action when Clavix is already initialized
+ */
+export declare function promptExistingConfigAction(): Promise<InitAction>;
+/**
+ * Prompt for what to do with deselected integrations
+ */
+export declare function promptDeselectedAction(): Promise<CleanupAction>;
+/**
+ * Prompt for Codex CLI confirmation
+ */
+export declare function promptCodexConfirmation(codexPath: string): Promise<boolean>;
+/**
+ * Prompt for namespace usage (Gemini/Qwen)
+ */
+export declare function promptNamespaceUsage(adapterDisplayName: string, defaultPath: string): Promise<boolean>;
+/**
+ * Prompt for continuing despite validation errors
+ */
+export declare function promptContinueAnyway(): Promise<boolean>;
+/**
+ * Prompt for removing legacy command files
+ */
+export declare function promptRemoveLegacy(adapter: AgentAdapter): Promise<boolean>;
+//# sourceMappingURL=prompts.d.ts.map