clavix 5.5.0 → 5.5.2

package/README.md

@@ -1,64 +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.5.0** (Latest) | Architecture cleanup, consolidated adapters, documentation overhaul | [Changelog](CHANGELOG.md) |
-| **v5.0.0** | Agentic-first architecture - lean template delivery | [Changelog](CHANGELOG.md#500---2025-01-27) |
-
-**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
 
@@ -69,80 +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)
+## 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

@@ -15,6 +15,7 @@ import { GeminiAdapter } from '../../core/adapters/gemini-adapter.js';
 import { QwenAdapter } from '../../core/adapters/qwen-adapter.js';
 import { loadCommandTemplates } from '../../utils/template-loader.js';
 import { collectLegacyCommandFiles } from '../../utils/legacy-command-cleanup.js';
+import { CLAVIX_BLOCK_START, CLAVIX_BLOCK_END } from '../../constants.js';
 export default class Init extends Command {
     static description = 'Initialize Clavix in the current project';
     static examples = ['<%= config.bin %> <%= command.id %>'];
@@ -76,8 +77,11 @@ export default class Init extends Command {
             // Select integrations using shared utility
             console.log(chalk.gray('Select AI development tools to support:\n'));
             console.log(chalk.gray('(Space to select, Enter to confirm)\n'));
-            const { selectIntegrations } = await import('../../utils/integration-selector.js');
-            const selectedIntegrations = await selectIntegrations(agentManager, existingIntegrations);
+            console.log(chalk.cyan('ℹ'), chalk.gray('AGENTS.md is always enabled to provide universal agent guidance.\n'));
+            const { selectIntegrations, ensureMandatoryIntegrations } = await import('../../utils/integration-selector.js');
+            const userSelectedIntegrations = await selectIntegrations(agentManager, existingIntegrations);
+            // Always include AGENTS.md
+            const selectedIntegrations = ensureMandatoryIntegrations(userSelectedIntegrations);
             if (!selectedIntegrations || selectedIntegrations.length === 0) {
                 console.log(chalk.red('\n✗ No integrations selected\n'));
                 return;
@@ -272,18 +276,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 +394,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
 
 \`\`\`
@@ -530,7 +557,8 @@ To reconfigure integrations, run \`clavix init\` again.
         }
     }
     extractClavixBlock(content) {
-        const match = content.match(/<!-- CLAVIX:START -->([\s\S]*?)<!-- CLAVIX:END -->/);
+        const regex = new RegExp(`${CLAVIX_BLOCK_START}([\\s\\S]*?)${CLAVIX_BLOCK_END}`);
+        const match = content.match(regex);
         return match ? match[1].trim() : content;
     }
 }

package/dist/cli/commands/update.js

@@ -3,8 +3,6 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import fs from 'fs-extra';
 import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
 import { DocInjector } from '../../core/doc-injector.js';
 import { AgentManager } from '../../core/agent-manager.js';
 import { AgentsMdGenerator } from '../../core/adapters/agents-md-generator.js';
@@ -12,8 +10,7 @@ import { OctoMdGenerator } from '../../core/adapters/octo-md-generator.js';
 import { WarpMdGenerator } from '../../core/adapters/warp-md-generator.js';
 import { InstructionsGenerator } from '../../core/adapters/instructions-generator.js';
 import { collectLegacyCommandFiles } from '../../utils/legacy-command-cleanup.js';
-const __filename = fileURLToPath(import.meta.url);
-const _dirname = dirname(__filename); // eslint-disable-line @typescript-eslint/no-unused-vars
+import { CLAVIX_BLOCK_START, CLAVIX_BLOCK_END } from '../../constants.js';
 export default class Update extends Command {
     static description = 'Update managed blocks and slash commands';
     static examples = [
@@ -135,8 +132,8 @@ export default class Update extends Command {
                 const currentContent = fs.readFileSync(claudePath, 'utf-8');
                 if (force || !this.hasUpToDateBlock(currentContent, claudeContent)) {
                     await DocInjector.injectBlock(claudePath, claudeContent, {
-                        startMarker: '<!-- CLAVIX:START -->',
-                        endMarker: '<!-- CLAVIX:END -->',
+                        startMarker: CLAVIX_BLOCK_START,
+                        endMarker: CLAVIX_BLOCK_END,
                     });
                     this.log(chalk.gray('  ✓ Updated CLAUDE.md'));
                     updated++;

package/dist/constants.d.ts

@@ -2,17 +2,6 @@
  * Clavix constants and magic values
  * Centralizes hardcoded values for maintainability
  */
-export declare const BACKUP_EXTENSION = ".backup";
-export declare const SEPARATOR_WIDTH = 50;
-export declare const SEPARATOR_CHAR = "\u2500";
 export declare const CLAVIX_BLOCK_START = "<!-- CLAVIX:START -->";
 export declare const CLAVIX_BLOCK_END = "<!-- CLAVIX:END -->";
-export declare const WINDSURF_CHAR_LIMIT = 12000;
-export declare const DEPTH_STANDARD = "standard";
-export declare const DEPTH_COMPREHENSIVE = "comprehensive";
-export declare const CLAVIX_CONFIG_DIR = ".clavix";
-export declare const CLAVIX_CONFIG_FILE = "config.json";
-export declare const CLAVIX_OUTPUTS_DIR = "outputs";
-export declare const CLAVIX_PROMPTS_DIR = "prompts";
-export declare const CLAVIX_TEMPLATES_DIR = "templates";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -2,23 +2,7 @@
  * Clavix constants and magic values
  * Centralizes hardcoded values for maintainability
  */
-// File system
-export const BACKUP_EXTENSION = '.backup';
-// CLI formatting
-export const SEPARATOR_WIDTH = 50;
-export const SEPARATOR_CHAR = '─';
 // Clavix managed block markers
 export const CLAVIX_BLOCK_START = '<!-- CLAVIX:START -->';
 export const CLAVIX_BLOCK_END = '<!-- CLAVIX:END -->';
-// Adapter-specific limits
-export const WINDSURF_CHAR_LIMIT = 12000;
-// Depth terminology (canonical)
-export const DEPTH_STANDARD = 'standard';
-export const DEPTH_COMPREHENSIVE = 'comprehensive';
-// File patterns
-export const CLAVIX_CONFIG_DIR = '.clavix';
-export const CLAVIX_CONFIG_FILE = 'config.json';
-export const CLAVIX_OUTPUTS_DIR = 'outputs';
-export const CLAVIX_PROMPTS_DIR = 'prompts';
-export const CLAVIX_TEMPLATES_DIR = 'templates';
 //# sourceMappingURL=constants.js.map

package/dist/core/adapter-registry.d.ts

@@ -7,6 +7,11 @@
  * For adapters requiring custom behavior (TOML format, doc injection),
  * dedicated adapter classes still exist.
  *
+ * NOTE: AGENTS.md is a mandatory integration that is always enabled by default.
+ * It provides universal agent guidance that all AI tools can read. The AGENTS.md
+ * adapter is handled separately via AgentsMdGenerator and is automatically
+ * included by ensureMandatoryIntegrations() in integration-selector.ts.
+ *
  * @since v5.3.0
  */
 import { AdapterConfig } from '../types/adapter-config.js';

package/dist/core/adapter-registry.js

@@ -7,6 +7,11 @@
  * For adapters requiring custom behavior (TOML format, doc injection),
  * dedicated adapter classes still exist.
  *
+ * NOTE: AGENTS.md is a mandatory integration that is always enabled by default.
+ * It provides universal agent guidance that all AI tools can read. The AGENTS.md
+ * adapter is handled separately via AgentsMdGenerator and is automatically
+ * included by ensureMandatoryIntegrations() in integration-selector.ts.
+ *
  * @since v5.3.0
  */
 import { DEFAULT_MD_FEATURES, DEFAULT_TOML_FEATURES, } from '../types/adapter-config.js';

package/dist/core/adapters/agents-md-generator.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { FileSystem } from '../../utils/file-system.js';
 import { DocInjector } from '../doc-injector.js';
+import { DataError } from '../../types/errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
@@ -17,7 +18,7 @@ export class AgentsMdGenerator {
     static async generate() {
         const templatePath = path.join(__dirname, '../../templates/agents/agents.md');
         if (!(await FileSystem.exists(templatePath))) {
-            throw new Error(`AGENTS.md template not found at ${templatePath}`);
+            throw new DataError(`AGENTS.md template not found at ${templatePath}`, "Check Clavix installation or run 'clavix update'");
         }
         const template = await FileSystem.readFile(templatePath);
         await DocInjector.injectBlock(this.TARGET_FILE, template, {

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

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { FileSystem } from '../../utils/file-system.js';
 import { DocInjector } from '../doc-injector.js';
+import { DataError } from '../../types/errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
@@ -17,7 +18,7 @@ export class CopilotInstructionsGenerator {
     static async generate() {
         const templatePath = path.join(__dirname, '../../templates/agents/copilot-instructions.md');
         if (!(await FileSystem.exists(templatePath))) {
-            throw new Error(`Copilot instructions template not found at ${templatePath}`);
+            throw new DataError(`Copilot instructions template not found at ${templatePath}`, "Check Clavix installation or run 'clavix update'");
         }
         const template = await FileSystem.readFile(templatePath);
         // Ensure .github directory exists

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

@@ -1,6 +1,7 @@
 import { FileSystem } from '../../utils/file-system.js';
 import { TemplateAssembler } from '../template-assembler.js';
 import { CommandTransformer } from '../command-transformer.js';
+import { DataError } from '../../types/errors.js';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
@@ -28,7 +29,7 @@ export class InstructionsGenerator {
         const staticInstructionsPath = path.join(__dirname, '../../templates/instructions');
         // Check if static template exists
         if (!(await FileSystem.exists(staticInstructionsPath))) {
-            throw new Error(`.clavix/instructions static files not found at ${staticInstructionsPath}`);
+            throw new DataError(`.clavix/instructions static files not found at ${staticInstructionsPath}`, "Check Clavix installation or run 'clavix update'");
         }
         // Create target directory
         await FileSystem.ensureDir(this.TARGET_DIR);
@@ -70,7 +71,7 @@ export class InstructionsGenerator {
         const canonicalPath = path.join(__dirname, '../../templates/slash-commands/_canonical');
         const workflowsTarget = path.join(this.TARGET_DIR, 'workflows');
         if (!(await FileSystem.exists(canonicalPath))) {
-            throw new Error(`Canonical templates not found at ${canonicalPath}`);
+            throw new DataError(`Canonical templates not found at ${canonicalPath}`, "Check Clavix installation or run 'clavix update'");
         }
         // Create workflows directory
         await FileSystem.ensureDir(workflowsTarget);

package/dist/core/adapters/octo-md-generator.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { FileSystem } from '../../utils/file-system.js';
 import { DocInjector } from '../doc-injector.js';
+import { DataError } from '../../types/errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
@@ -17,7 +18,7 @@ export class OctoMdGenerator {
     static async generate() {
         const templatePath = path.join(__dirname, '../../templates/agents/octo.md');
         if (!(await FileSystem.exists(templatePath))) {
-            throw new Error(`OCTO.md template not found at ${templatePath}`);
+            throw new DataError(`OCTO.md template not found at ${templatePath}`, "Check Clavix installation or run 'clavix update'");
         }
         const template = await FileSystem.readFile(templatePath);
         await DocInjector.injectBlock(this.TARGET_FILE, template, {

package/dist/core/adapters/warp-md-generator.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { FileSystem } from '../../utils/file-system.js';
 import { DocInjector } from '../doc-injector.js';
+import { DataError } from '../../types/errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
@@ -17,7 +18,7 @@ export class WarpMdGenerator {
     static async generate() {
         const templatePath = path.join(__dirname, '../../templates/agents/warp.md');
         if (!(await FileSystem.exists(templatePath))) {
-            throw new Error(`WARP.md template not found at ${templatePath}`);
+            throw new DataError(`WARP.md template not found at ${templatePath}`, "Check Clavix installation or run 'clavix update'");
         }
         const template = await FileSystem.readFile(templatePath);
         await DocInjector.injectBlock(this.TARGET_FILE, template, {

package/dist/core/doc-injector.js

@@ -3,12 +3,13 @@ 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';
+import { CLAVIX_BLOCK_START, CLAVIX_BLOCK_END } from '../constants.js';
 /**
  * DocInjector - manages injection and updating of managed blocks in documentation files
  */
 export class DocInjector {
-    static DEFAULT_START_MARKER = '<!-- CLAVIX:START -->';
-    static DEFAULT_END_MARKER = '<!-- CLAVIX:END -->';
+    static DEFAULT_START_MARKER = CLAVIX_BLOCK_START;
+    static DEFAULT_END_MARKER = CLAVIX_BLOCK_END;
     /**
      * Inject or update managed block in a file
      */
@@ -194,6 +195,11 @@ Enter conversational mode for iterative prompt development. Discuss your require
 #### /clavix:summarize
 Analyze the current conversation and extract key requirements into a structured prompt and mini-PRD.
 
+### Refinement
+
+#### /clavix:refine
+Refine existing PRD or prompt through continued discussion. Detects available PRDs and saved prompts, then guides you through updating them with tracked changes.
+
 ### Agentic Utilities
 
 These utilities provide structured workflows for common tasks. Invoke them using the slash commands below:
@@ -207,10 +213,11 @@ These utilities provide structured workflows for common tasks. Invoke them using
 
 **Recommended Workflow:**
 1. Start with \`/clavix:prd\` or \`/clavix:start\` for complex features
-2. Generate tasks with \`/clavix:plan\`
-3. Implement with \`/clavix:implement\`
-4. Verify with \`/clavix:verify\`
-5. Archive when complete with \`/clavix:archive\`
+2. Refine requirements with \`/clavix:refine\` as needed
+3. Generate tasks with \`/clavix:plan\`
+4. Implement with \`/clavix:implement\`
+5. Verify with \`/clavix:verify\`
+6. Archive when complete with \`/clavix:archive\`
 
 **Pro tip**: Start complex features with \`/clavix:prd\` or \`/clavix:start\` to ensure clear requirements before implementation.`;
     }

package/dist/templates/agents/agents.md

@@ -60,6 +60,7 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 | "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
 | "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
 | "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
+| "refine", "update PRD", "change requirements", "modify prompt" | Refine mode → Update existing content | `workflows/refine.md` |
 | "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
 
 **When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
@@ -87,6 +88,7 @@ All workflows are executed via slash commands that AI agents read and follow:
 | `/clavix:implement` | Execute tasks or prompts (auto-detects source) |
 | `/clavix:start` | Begin conversational session |
 | `/clavix:summarize` | Extract requirements from conversation |
+| `/clavix:refine` | Refine existing PRD or saved prompt |
 
 ### Agentic Utilities (Project Management)
 These utilities provide structured workflows for project completion: