clavix 5.8.2 → 5.9.1

package/dist/cli/commands/init.js

@@ -25,8 +25,8 @@ export default class Init extends Command {
     async run() {
         this.log(chalk.bold.cyan('\n🚀 Clavix Initialization\n'));
         try {
-            const agentManager = new AgentManager();
             let existingIntegrations = [];
+            let existingConfig;
             // Load existing config if present
             if (await FileSystem.exists('.clavix/config.json')) {
                 try {
@@ -37,6 +37,7 @@ export default class Init extends Command {
                     if (validationResult.success && validationResult.data) {
                         existingIntegrations =
                             validationResult.data.integrations || validationResult.data.providers || [];
+                        existingConfig = validationResult.data;
                         // Log warnings (non-blocking)
                         if (validationResult.warnings) {
                             for (const warning of validationResult.warnings) {
@@ -60,6 +61,8 @@ export default class Init extends Command {
                     // Continue with empty array - will prompt for new configuration
                 }
             }
+            // Initialize agent manager with existing config (for custom integration paths)
+            const agentManager = new AgentManager(existingConfig);
             // Check if already initialized
             if (await FileSystem.exists('.clavix')) {
                 // Show current state
@@ -176,12 +179,93 @@ export default class Init extends Command {
                 }
                 // If 'skip': do nothing
             }
+            // Collect custom integration paths (e.g., for Codex with $CODEX_HOME)
+            const integrationPaths = {};
+            // Prompt about Codex path if Codex is selected
+            if (selectedIntegrations.includes('codex')) {
+                this.log(chalk.cyan('\n🔧 Codex Configuration'));
+                const hasEnvVar = process.env.CODEX_HOME;
+                const defaultPath = '~/.codex/prompts';
+                if (hasEnvVar) {
+                    // $CODEX_HOME is detected - ask for confirmation
+                    const { useEnvPath } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'useEnvPath',
+                            message: `Detected $CODEX_HOME=${hasEnvVar}. Use this path instead of ${defaultPath}?`,
+                            default: true,
+                        },
+                    ]);
+                    if (useEnvPath) {
+                        integrationPaths.codex = hasEnvVar;
+                        this.log(chalk.gray(`  ✓ Using $CODEX_HOME: ${hasEnvVar}`));
+                    }
+                    else {
+                        // Ask if they want to use a custom path
+                        const { useCustomPath } = await inquirer.prompt([
+                            {
+                                type: 'confirm',
+                                name: 'useCustomPath',
+                                message: 'Use a custom Codex prompts directory?',
+                                default: false,
+                            },
+                        ]);
+                        if (useCustomPath) {
+                            const { customPath } = await inquirer.prompt([
+                                {
+                                    type: 'input',
+                                    name: 'customPath',
+                                    message: 'Enter path to Codex prompts directory:',
+                                    default: defaultPath,
+                                    validate: (input) => {
+                                        if (!input || input.trim().length === 0) {
+                                            return 'Path cannot be empty';
+                                        }
+                                        return true;
+                                    },
+                                },
+                            ]);
+                            integrationPaths.codex = customPath;
+                            this.log(chalk.gray(`  ✓ Using custom path: ${customPath}`));
+                        }
+                    }
+                }
+                else {
+                    // No $CODEX_HOME - ask if they want a custom path
+                    const { useCustomPath } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'useCustomPath',
+                            message: 'Use a custom Codex prompts directory?',
+                            default: false,
+                        },
+                    ]);
+                    if (useCustomPath) {
+                        const { customPath } = await inquirer.prompt([
+                            {
+                                type: 'input',
+                                name: 'customPath',
+                                message: 'Enter path to Codex prompts directory:',
+                                default: defaultPath,
+                                validate: (input) => {
+                                    if (!input || input.trim().length === 0) {
+                                        return 'Path cannot be empty';
+                                    }
+                                    return true;
+                                },
+                            },
+                        ]);
+                        integrationPaths.codex = customPath;
+                        this.log(chalk.gray(`  ✓ Using custom path: ${customPath}`));
+                    }
+                }
+            }
             // Create .clavix directory structure
             this.log(chalk.cyan('\n📁 Creating directory structure...'));
             await this.createDirectoryStructure();
             // Generate config
             this.log(chalk.cyan('⚙️  Generating configuration...'));
-            await this.generateConfig(selectedIntegrations);
+            await this.generateConfig(selectedIntegrations, integrationPaths);
             // Generate INSTRUCTIONS.md and QUICKSTART.md
             await this.generateInstructions();
             await this.generateQuickstart();
@@ -396,11 +480,17 @@ export default class Init extends Command {
             await FileSystem.ensureDir(dir);
         }
     }
-    async generateConfig(integrations) {
+    async generateConfig(integrations, integrationPaths = {}) {
         const config = {
             ...DEFAULT_CONFIG,
             integrations,
         };
+        // Add integration paths to experimental if any
+        if (Object.keys(integrationPaths).length > 0) {
+            config.experimental = {
+                integrationPaths,
+            };
+        }
         const configPath = '.clavix/config.json';
         const configContent = JSON.stringify(config, null, 2);
         await FileSystem.writeFileAtomic(configPath, configContent);

package/dist/cli/commands/update.js

@@ -72,6 +72,8 @@ export default class Update extends Command {
                     this.log(chalk.yellow(`  ⚠ ${warning}`));
                 }
             }
+            // Type assertion: validationResult.data is User type which has optional version
+            // We know version exists in valid configs, so we can assert
             config = validationResult.data;
         }
         catch (error) {
@@ -84,8 +86,10 @@ export default class Update extends Command {
                 chalk.cyan('clavix init') +
                 chalk.yellow(' to regenerate.'));
         }
+        // Handle legacy 'providers' field for backward compatibility
         const integrations = config.integrations || config.providers || ['claude-code'];
-        const agentManager = new AgentManager();
+        // Initialize agent manager with config (for custom integration paths)
+        const agentManager = new AgentManager(config);
         const updateDocs = flags['docs-only'] || (!flags['docs-only'] && !flags['commands-only']);
         const updateCommands = flags['commands-only'] || (!flags['docs-only'] && !flags['commands-only']);
         let updatedCount = 0;

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

@@ -12,7 +12,7 @@ export declare function loadExistingConfig(): Promise<{
 /**
  * Generate and save the Clavix config file
  */
-export declare function generateConfig(integrations: string[]): Promise<void>;
+export declare function generateConfig(integrations: string[], integrationPaths?: Record<string, string>): Promise<void>;
 /**
  * Check if Clavix is already initialized in the current directory
  */

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

@@ -31,11 +31,17 @@ export async function loadExistingConfig() {
 /**
  * Generate and save the Clavix config file
  */
-export async function generateConfig(integrations) {
+export async function generateConfig(integrations, integrationPaths = {}) {
     const config = {
         ...DEFAULT_CONFIG,
         integrations,
     };
+    // Add integration paths to experimental if any
+    if (Object.keys(integrationPaths).length > 0) {
+        config.experimental = {
+            integrationPaths,
+        };
+    }
     const configPath = '.clavix/config.json';
     const configContent = JSON.stringify(config, null, 2);
     await FileSystem.writeFileAtomic(configPath, configContent);

package/dist/core/adapters/claude-code-adapter.d.ts

@@ -1,5 +1,6 @@
 import { BaseAdapter } from './base-adapter.js';
 import { ManagedBlock } from '../../types/agent.js';
+import { ClavixConfig } from '../../types/config.js';
 /**
  * Claude Code agent adapter
  */
@@ -11,6 +12,8 @@ export declare class ClaudeCodeAdapter extends BaseAdapter {
     readonly features: {
         supportsSubdirectories: boolean;
     };
+    protected readonly userConfig?: ClavixConfig;
+    constructor(userConfig?: ClavixConfig);
     /**
      * Detect if Claude Code is available in the project
      */

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

@@ -14,6 +14,11 @@ export class ClaudeCodeAdapter extends BaseAdapter {
     features = {
         supportsSubdirectories: true,
     };
+    userConfig;
+    constructor(userConfig) {
+        super();
+        this.userConfig = userConfig;
+    }
     /**
      * Detect if Claude Code is available in the project
      */

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

@@ -1,11 +1,13 @@
 import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
+import { ClavixConfig } from '../../types/config.js';
 /**
  * Gemini CLI adapter
  * Commands stored as TOML files under .gemini/commands/clavix by default
  */
 export declare class GeminiAdapter extends TomlFormattingAdapter {
-    constructor(options?: {
+    constructor(userConfigOrOptions?: ClavixConfig | {
         useNamespace?: boolean;
+        userConfig?: ClavixConfig;
     });
 }
 //# sourceMappingURL=gemini-adapter.d.ts.map

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

@@ -4,12 +4,31 @@ import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
  * Commands stored as TOML files under .gemini/commands/clavix by default
  */
 export class GeminiAdapter extends TomlFormattingAdapter {
-    constructor(options = {}) {
-        super({
-            name: 'gemini',
-            displayName: 'Gemini CLI',
-            rootDir: '.gemini',
-        }, options);
+    constructor(userConfigOrOptions) {
+        // Support both old API (options object) and new API (userConfig directly)
+        if (!userConfigOrOptions) {
+            super({
+                name: 'gemini',
+                displayName: 'Gemini CLI',
+                rootDir: '.gemini',
+            });
+        }
+        else if ('useNamespace' in userConfigOrOptions) {
+            // It's the options object
+            super({
+                name: 'gemini',
+                displayName: 'Gemini CLI',
+                rootDir: '.gemini',
+            }, userConfigOrOptions);
+        }
+        else {
+            // It's the userConfig directly - pass as options
+            super({
+                name: 'gemini',
+                displayName: 'Gemini CLI',
+                rootDir: '.gemini',
+            }, { userConfig: userConfigOrOptions });
+        }
     }
 }
 //# sourceMappingURL=gemini-adapter.js.map

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

@@ -1,11 +1,13 @@
 import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
+import { ClavixConfig } from '../../types/config.js';
 /**
  * LLXPRT adapter
  * Commands stored as TOML files under .llxprt/commands/clavix by default
  */
 export declare class LlxprtAdapter extends TomlFormattingAdapter {
-    constructor(options?: {
+    constructor(userConfigOrOptions?: ClavixConfig | {
         useNamespace?: boolean;
+        userConfig?: ClavixConfig;
     });
 }
 //# sourceMappingURL=llxprt-adapter.d.ts.map

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

@@ -4,12 +4,31 @@ import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
  * Commands stored as TOML files under .llxprt/commands/clavix by default
  */
 export class LlxprtAdapter extends TomlFormattingAdapter {
-    constructor(options = {}) {
-        super({
-            name: 'llxprt',
-            displayName: 'LLXPRT',
-            rootDir: '.llxprt',
-        }, options);
+    constructor(userConfigOrOptions) {
+        // Support both old API (options object) and new API (userConfig directly)
+        if (!userConfigOrOptions) {
+            super({
+                name: 'llxprt',
+                displayName: 'LLXPRT',
+                rootDir: '.llxprt',
+            });
+        }
+        else if ('useNamespace' in userConfigOrOptions) {
+            // It's the options object
+            super({
+                name: 'llxprt',
+                displayName: 'LLXPRT',
+                rootDir: '.llxprt',
+            }, userConfigOrOptions);
+        }
+        else {
+            // It's the userConfig directly - pass as options
+            super({
+                name: 'llxprt',
+                displayName: 'LLXPRT',
+                rootDir: '.llxprt',
+            }, { userConfig: userConfigOrOptions });
+        }
     }
 }
 //# sourceMappingURL=llxprt-adapter.js.map

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

@@ -1,11 +1,13 @@
 import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
+import { ClavixConfig } from '../../types/config.js';
 /**
  * Qwen Code CLI adapter
  * Commands stored as TOML files under .qwen/commands/clavix by default
  */
 export declare class QwenAdapter extends TomlFormattingAdapter {
-    constructor(options?: {
+    constructor(userConfigOrOptions?: ClavixConfig | {
         useNamespace?: boolean;
+        userConfig?: ClavixConfig;
     });
 }
 //# sourceMappingURL=qwen-adapter.d.ts.map

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

@@ -4,12 +4,31 @@ import { TomlFormattingAdapter } from './toml-formatting-adapter.js';
  * Commands stored as TOML files under .qwen/commands/clavix by default
  */
 export class QwenAdapter extends TomlFormattingAdapter {
-    constructor(options = {}) {
-        super({
-            name: 'qwen',
-            displayName: 'Qwen Code',
-            rootDir: '.qwen',
-        }, options);
+    constructor(userConfigOrOptions) {
+        // Support both old API (options object) and new API (userConfig directly)
+        if (!userConfigOrOptions) {
+            super({
+                name: 'qwen',
+                displayName: 'Qwen Code',
+                rootDir: '.qwen',
+            });
+        }
+        else if ('useNamespace' in userConfigOrOptions) {
+            // It's the options object
+            super({
+                name: 'qwen',
+                displayName: 'Qwen Code',
+                rootDir: '.qwen',
+            }, userConfigOrOptions);
+        }
+        else {
+            // It's the userConfig directly - pass as options
+            super({
+                name: 'qwen',
+                displayName: 'Qwen Code',
+                rootDir: '.qwen',
+            }, { userConfig: userConfigOrOptions });
+        }
     }
 }
 //# sourceMappingURL=qwen-adapter.js.map

package/dist/core/adapters/toml-formatting-adapter.d.ts

@@ -1,5 +1,6 @@
 import { BaseAdapter } from './base-adapter.js';
 import { CommandTemplate } from '../../types/agent.js';
+import { ClavixConfig } from '../../types/config.js';
 /**
  * Configuration for TOML-based adapters
  */
@@ -30,8 +31,10 @@ export declare abstract class TomlFormattingAdapter extends BaseAdapter {
         argumentPlaceholder: string;
     };
     protected readonly config: TomlAdapterConfig;
+    protected readonly userConfig?: ClavixConfig;
     constructor(config: TomlAdapterConfig, options?: {
         useNamespace?: boolean;
+        userConfig?: ClavixConfig;
     });
     get name(): string;
     get displayName(): string;

package/dist/core/adapters/toml-formatting-adapter.js

@@ -19,12 +19,14 @@ export class TomlFormattingAdapter extends BaseAdapter {
         argumentPlaceholder: '{{args}}',
     };
     config;
+    userConfig;
     constructor(config, options = {}) {
         super();
         this.config = {
             ...config,
             useNamespace: options.useNamespace ?? config.useNamespace ?? true,
         };
+        this.userConfig = options.userConfig;
     }
     get name() {
         return this.config.name;

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

@@ -13,10 +13,12 @@
 import { BaseAdapter } from './base-adapter.js';
 import { AdapterConfig } from '../../types/adapter-config.js';
 import { IntegrationFeatures } from '../../types/agent.js';
+import { ClavixConfig } from '../../types/config.js';
 export declare class UniversalAdapter extends BaseAdapter {
     private config;
     readonly features: IntegrationFeatures;
-    constructor(config: AdapterConfig);
+    private userConfig?;
+    constructor(config: AdapterConfig, userConfig?: ClavixConfig);
     get name(): string;
     get displayName(): string;
     get directory(): string;

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

@@ -11,14 +11,16 @@
  * @since v5.3.0
  */
 import { BaseAdapter } from './base-adapter.js';
+import { resolveIntegrationPath } from '../../utils/path-resolver.js';
 import * as path from 'path';
-import * as os from 'os';
 export class UniversalAdapter extends BaseAdapter {
     config;
     features;
-    constructor(config) {
+    userConfig;
+    constructor(config, userConfig) {
         super();
         this.config = config;
+        this.userConfig = userConfig;
         // Set features from config for interface compatibility
         this.features = {
             supportsSubdirectories: config.features.supportsSubdirectories,
@@ -34,11 +36,8 @@ export class UniversalAdapter extends BaseAdapter {
         return this.config.displayName;
     }
     get directory() {
-        // Expand ~ to home directory for global adapters
-        if (this.config.directory.startsWith('~/')) {
-            return this.config.directory.replace('~', os.homedir());
-        }
-        return this.config.directory;
+        // Use path resolver for proper environment variable and config override support
+        return resolveIntegrationPath(this.config, this.userConfig);
     }
     /**
      * Check if this adapter uses global (home directory) installation

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

@@ -1,4 +1,5 @@
 import { AgentAdapter, ValidationResult } from '../types/agent.js';
+import { ClavixConfig } from '../types/config.js';
 /**
  * Agent Manager - handles agent detection and registration
  *
@@ -9,7 +10,8 @@ import { AgentAdapter, ValidationResult } from '../types/agent.js';
  */
 export declare class AgentManager {
     private adapters;
-    constructor();
+    private userConfig?;
+    constructor(userConfig?: ClavixConfig);
     /**
      * Register a new agent adapter
      */

package/dist/core/agent-manager.js

@@ -15,18 +15,20 @@ import { IntegrationError } from '../types/errors.js';
  */
 export class AgentManager {
     adapters = new Map();
-    constructor() {
+    userConfig;
+    constructor(userConfig) {
+        this.userConfig = userConfig;
         // 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
+        this.registerAdapter(new ClaudeCodeAdapter(userConfig)); // Doc injection
+        this.registerAdapter(new GeminiAdapter(userConfig)); // TOML format
+        this.registerAdapter(new QwenAdapter(userConfig)); // TOML format
+        this.registerAdapter(new LlxprtAdapter(userConfig)); // 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));
+            this.registerAdapter(new UniversalAdapter(config, userConfig));
         }
     }
     /**

package/dist/templates/slash-commands/_canonical/archive.md

@@ -274,7 +274,7 @@ Result: Project permanently deleted
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/implement.md

@@ -524,7 +524,7 @@ I'll explain what's wrong and what you might need to do:
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/improve.md

@@ -524,7 +524,7 @@ Wait for the user to decide what to do next.
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/plan.md

@@ -107,30 +107,37 @@ Implementation: BLOCKED - I will create the plan, not the code
    - Check `.clavix/outputs/<project-name>/` for `full-prd.md`, `quick-prd.md`, etc.
    - If missing, check legacy `.clavix/outputs/summarize/`.
 2. **Read PRD**: Ingest the requirements.
+3. **Extract Architecture**: Look for the "Architecture & Design" section. Note any specific patterns (e.g., Clean Architecture, Feature-Sliced Design) or structural decisions.
 
 #### **Phase 3: Task Generation**
-1. **Synthesize**: Combine [PRD Requirements] + [Codebase Patterns].
-2. **Draft Tasks**: Create tasks that specify *exactly* what to change in the code.
-3. **Create `tasks.md`**: Use the format in "Task Format Reference".
-4. **Save to**: `.clavix/outputs/[project-name]/tasks.md`.
+1. **Synthesize**: Combine [PRD Requirements] + [Codebase Patterns] + [Architecture Decisions].
+2. **Prioritize Structure**: Ensure initial tasks cover any necessary architectural setup (e.g., creating folders for new layers, setting up base classes).
+3. **Draft Tasks**: Create tasks that specify *exactly* what to change in the code.
+4. **Create `tasks.md`**: Use the format in "Task Format Reference".
+5. **Save to**: `.clavix/outputs/[project-name]/tasks.md`.
 
 ### Part B: Behavioral Guidance (Technical Specificity)
 
 **Your goal is "Low-Level Engineering Plans", not "High-Level Management Plans".**
 
-1. **Specific File Paths**:
+1. **Architecture First**:
+   - If the PRD specifies a pattern (e.g., Repository), the first tasks MUST set up that structure.
+   - **Bad**: "Implement user feature."
+   - **Good**: "Create `src/repositories/UserRepository.ts` interface first, then implementation."
+
+2. **Specific File Paths**:
    - **Bad**: "Create a user profile component."
    - **Good**: "Create `src/components/user/UserProfile.tsx`. Export as default."
 
-2. **Technical Constraints**:
+3. **Technical Constraints**:
    - **Bad**: "Add validation."
    - **Good**: "Use `zod` schema in `src/schemas/user.ts`. Integrate with `react-hook-form`."
 
-3. **Respect Existing Architecture**:
+4. **Respect Existing Architecture**:
    - If the project uses a `services/` folder for API calls, do **not** put `fetch` calls directly in components.
    - If the project uses `shadcn/ui`, instruct to use those primitives, not raw HTML.
 
-4. **Granularity**:
+5. **Granularity**:
    - Each task should be a single logical unit of work (approx. 20-40 mins).
    - Separate "Backend API" from "Frontend UI" tasks.
    - Separate "Type Definition" from "Implementation" if complex.
@@ -150,6 +157,7 @@ Implementation: BLOCKED - I will create the plan, not the code
 
 ## Technical Context & Standards
 *Detected Stack & Patterns*
+- **Architecture**: {e.g., Feature-Sliced Design, Monolith}
 - **Framework**: {e.g., Next.js 14 App Router}
 - **Styling**: {e.g., Tailwind CSS + shadcn/ui}
 - **State**: {e.g., Zustand (stores in /src/store)}
@@ -221,7 +229,7 @@ Present the plan and ask:
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/prd.md

@@ -125,6 +125,11 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
      - "Are there performance requirements (load time, concurrent users)?"
    - **If "I don't know"**: Suggest common stacks based on project type or skip
 
+   **Question 3.5**: Any specific architectural patterns or design choices?
+
+   - **Optional**
+   - **Prompt**: "Do you have preferences for folder structure, design patterns (e.g., Repository, Adapter), or architectural style (Monolith vs Microservices)?"
+
    **Question 4**: What is explicitly OUT of scope? (What are we NOT building?)
 
    - **Validation**: At least 1 explicit exclusion
@@ -136,7 +141,7 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
 
    **Question 5**: Any additional context or requirements?
 
-   - **Optional**: Press Enter to skip
+   - **Optional**
    - **Helpful areas**: Compliance needs, accessibility, localization, deadlines, team constraints
 
 2. **Before proceeding to document generation**, verify minimum viable answers:
@@ -161,6 +166,9 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
    ### Technical Requirements
    [User's answer to Q3, detailed]
 
+   ### Architecture & Design
+   [User's answer to Q3.5 if provided]
+
    ## Out of Scope
    [User's answer to Q4]
 
@@ -346,7 +354,7 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/refine.md

@@ -415,7 +415,7 @@ I'll update the PRD and add this to the refinement history. Confirm?
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/start.md

@@ -98,6 +98,7 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
 2. As the user describes their needs:
    - Ask clarifying questions about unclear points
    - Probe for technical constraints
+   - Probe for architectural preferences (e.g., 'Do you need a specific structure like Clean Architecture, Microservices, or Feature-Sliced Design?')
    - Explore edge cases and requirements
    - Help them think through user needs
    - Identify potential challenges
@@ -117,6 +118,7 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
    - Target users
    - Core features
    - Technical requirements
+   - Architecture & Design
    - Success criteria
    - Constraints and scope
 
@@ -228,7 +230,7 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/summarize.md

@@ -115,6 +115,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
    - **Problem/Goal** [confidence]: What is the user trying to build or solve?
    - **Key Requirements** [confidence per requirement]: What features and functionality were discussed?
    - **Technical Constraints** [confidence]: Any technologies, integrations, or performance needs?
+   - **Architecture & Design** [confidence]: Any specific patterns, structures, or design choices?
    - **User Needs** [confidence]: Who are the end users and what do they need?
    - **Success Criteria** [confidence]: How will success be measured?
    - **Context** [confidence]: Any important background or constraints?
@@ -197,6 +198,11 @@ Implementation: BLOCKED - I will extract requirements, not implement them
    - **Integrations:** [External systems]
    - **Other:** [Any other technical constraints]
 
+   ## Architecture & Design
+   - **Pattern:** [e.g. Monolith, Microservices, Serverless]
+   - **Structure:** [e.g. Feature-based, Layered, Clean Architecture]
+   - **Key Decisions:** [Specific design choices made]
+
    ## User Context
    **Target Users:** [Who will use this?]
    **Primary Use Case:** [Main problem being solved]
@@ -403,7 +409,7 @@ The `/clavix:summarize` command extracts requirements from exploratory conversat
 
 ---
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/verify.md

@@ -123,7 +123,7 @@ Implementation: BLOCKED - I'll analyze and report, not modify or fix
 
 ----
 
-## Agent Transparency (v5.8.2)
+## Agent Transparency (v5.9.1)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/types/config.d.ts

@@ -7,7 +7,9 @@ export interface ClavixConfig {
     templates: TemplateConfig;
     outputs: OutputConfig;
     preferences: PreferencesConfig;
-    experimental?: Record<string, unknown>;
+    experimental?: Record<string, unknown> & {
+        integrationPaths?: IntegrationPathsConfig;
+    };
 }
 /**
  * Legacy config format (pre-v3.5.0)
@@ -37,6 +39,13 @@ export interface PreferencesConfig {
     autoOpenOutputs: boolean;
     verboseLogging: boolean;
 }
+/**
+ * Custom directory paths for integrations
+ * Maps integration name (e.g., 'codex') to custom directory path
+ */
+export interface IntegrationPathsConfig {
+    [integrationName: string]: string;
+}
 export declare const DEFAULT_CONFIG: ClavixConfig;
 /**
  * Migrate legacy config to current format (v3.5.0+)

package/dist/utils/path-resolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Path resolution utility for integration directories
+ *
+ * Supports environment variable overrides with proper priority:
+ * 1. Environment variable (e.g., $CODEX_HOME)
+ * 2. User config override (experimental.integrationPaths)
+ * 3. Built-in default from integrations.json
+ */
+import type { ClavixConfig } from '../types/config.js';
+import type { AdapterConfig } from '../types/adapter-config.js';
+/**
+ * Mapping of integration names to their environment variable names
+ *
+ * Future extensibility: Add more integrations here as needed
+ */
+export declare const ENV_VAR_MAP: Record<string, string>;
+/**
+ * Resolves the directory path for an integration based on priority:
+ * 1. Environment variable (highest priority)
+ * 2. User config override
+ * 3. Built-in default (fallback)
+ *
+ * @param config - The adapter configuration from integrations.json
+ * @param userConfig - The user's Clavix config (optional)
+ * @returns The resolved directory path with tilde expansion
+ */
+export declare function resolveIntegrationPath(config: AdapterConfig, userConfig?: ClavixConfig): string;
+//# sourceMappingURL=path-resolver.d.ts.map

package/dist/utils/path-resolver.js

@@ -0,0 +1,57 @@
+/**
+ * Path resolution utility for integration directories
+ *
+ * Supports environment variable overrides with proper priority:
+ * 1. Environment variable (e.g., $CODEX_HOME)
+ * 2. User config override (experimental.integrationPaths)
+ * 3. Built-in default from integrations.json
+ */
+import * as os from 'os';
+/**
+ * Mapping of integration names to their environment variable names
+ *
+ * Future extensibility: Add more integrations here as needed
+ */
+export const ENV_VAR_MAP = {
+    codex: 'CODEX_HOME',
+    // Future: cursor: 'CURSOR_HOME',
+    // Future: gemini: 'GEMINI_HOME',
+};
+/**
+ * Resolves the directory path for an integration based on priority:
+ * 1. Environment variable (highest priority)
+ * 2. User config override
+ * 3. Built-in default (fallback)
+ *
+ * @param config - The adapter configuration from integrations.json
+ * @param userConfig - The user's Clavix config (optional)
+ * @returns The resolved directory path with tilde expansion
+ */
+export function resolveIntegrationPath(config, userConfig) {
+    const integrationName = config.name;
+    // Priority 1: Environment variable
+    const envVar = ENV_VAR_MAP[integrationName];
+    if (envVar && process.env[envVar]) {
+        return process.env[envVar];
+    }
+    // Priority 2: User config override
+    const customPath = userConfig?.experimental?.integrationPaths?.[integrationName];
+    if (customPath && typeof customPath === 'string') {
+        return expandTilde(customPath);
+    }
+    // Priority 3: Built-in default from config
+    return expandTilde(config.directory);
+}
+/**
+ * Expands tilde (~) to the user's home directory
+ *
+ * @param dir - Directory path that may start with ~/
+ * @returns Directory path with ~ expanded to home directory
+ */
+function expandTilde(dir) {
+    if (dir.startsWith('~/')) {
+        return dir.replace('~', os.homedir());
+    }
+    return dir;
+}
+//# sourceMappingURL=path-resolver.js.map

package/dist/utils/schemas.d.ts

@@ -119,7 +119,6 @@ export declare const IntegrationsConfigSchema: z.ZodObject<{
         placeholder?: string | undefined;
     }[]>;
 }, "strip", z.ZodTypeAny, {
-    version: string;
     integrations: {
         name: string;
         directory: string;
@@ -134,9 +133,9 @@ export declare const IntegrationsConfigSchema: z.ZodObject<{
         global?: boolean | undefined;
         placeholder?: string | undefined;
     }[];
+    version: string;
     $schema?: string | undefined;
 }, {
-    version: string;
     integrations: {
         name: string;
         directory: string;
@@ -151,8 +150,14 @@ export declare const IntegrationsConfigSchema: z.ZodObject<{
         global?: boolean | undefined;
         placeholder?: string | undefined;
     }[];
+    version: string;
     $schema?: string | undefined;
 }>;
+/**
+ * Schema for integration paths in experimental config
+ * Maps integration name to custom directory path
+ */
+export declare const IntegrationPathsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 /**
  * Schema for user's .clavix/config.json
  * Matches ClavixConfig interface in src/types/config.ts
@@ -194,11 +199,17 @@ export declare const UserConfigSchema: z.ZodObject<{
         autoOpenOutputs: boolean;
         verboseLogging: boolean;
     }>>;
-    experimental: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    experimental: z.ZodOptional<z.ZodObject<{
+        integrationPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        integrationPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        integrationPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
-    version?: string | undefined;
-    integrations?: string[] | undefined;
     providers?: string[] | undefined;
+    integrations?: string[] | undefined;
+    version?: string | undefined;
     templates?: {
         prdQuestions: string;
         fullPrd: string;
@@ -212,11 +223,13 @@ export declare const UserConfigSchema: z.ZodObject<{
         autoOpenOutputs: boolean;
         verboseLogging: boolean;
     } | undefined;
-    experimental?: Record<string, unknown> | undefined;
+    experimental?: z.objectOutputType<{
+        integrationPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
-    version?: string | undefined;
-    integrations?: string[] | undefined;
     providers?: string[] | undefined;
+    integrations?: string[] | undefined;
+    version?: string | undefined;
     templates?: {
         prdQuestions: string;
         fullPrd: string;
@@ -230,7 +243,9 @@ export declare const UserConfigSchema: z.ZodObject<{
         autoOpenOutputs: boolean;
         verboseLogging: boolean;
     } | undefined;
-    experimental?: Record<string, unknown> | undefined;
+    experimental?: z.objectInputType<{
+        integrationPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
 /**
  * Inferred TypeScript types from schemas

package/dist/utils/schemas.js

@@ -63,6 +63,21 @@ const PreferencesConfigSchema = z.object({
     autoOpenOutputs: z.boolean(),
     verboseLogging: z.boolean(),
 });
+/**
+ * Schema for integration paths in experimental config
+ * Maps integration name to custom directory path
+ */
+export const IntegrationPathsSchema = z
+    .record(z.string().min(1, 'Integration name is required'), z.string().min(1, 'Path cannot be empty'))
+    .optional();
+/**
+ * Schema for experimental configuration
+ */
+const ExperimentalConfigSchema = z
+    .object({
+    integrationPaths: IntegrationPathsSchema,
+})
+    .passthrough(); // Allow other experimental fields
 /**
  * Schema for user's .clavix/config.json
  * Matches ClavixConfig interface in src/types/config.ts
@@ -78,7 +93,7 @@ export const UserConfigSchema = z.object({
     templates: TemplateConfigSchema.optional(),
     outputs: OutputConfigSchema.optional(),
     preferences: PreferencesConfigSchema.optional(),
-    experimental: z.record(z.unknown()).optional(),
+    experimental: ExperimentalConfigSchema.optional(),
 });
 /**
  * Validate integrations.json content (build-time, strict)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.8.2",
+  "version": "5.9.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  /clavix:refine     Refine existing PRD or prompt\n  /clavix:verify     Verify implementation against requirements\n  /clavix:archive    Archive completed projects\n\nWorks with Claude Code, Cursor, Windsurf, and 20 AI coding tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -70,6 +70,7 @@
     "@oclif/core": "^4.8.0",
     "@oclif/plugin-help": "^6.2.35",
     "chalk": "^5.6.2",
+    "clavix": "^5.9.0",
     "fs-extra": "^11.3.2",
     "inquirer": "^12.11.1",
     "zod": "^3.24.4"