clavix 5.5.1 → 5.6.0

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

@@ -14,5 +14,6 @@ export default class Init extends Command {
     private handleLegacyCommands;
     private injectDocumentation;
     private extractClavixBlock;
+    private generateQuickstart;
 }
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.js

@@ -2,7 +2,10 @@ import { Command } from '@oclif/core';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { AgentManager } from '../../core/agent-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 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';
@@ -15,6 +18,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 +80,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;
@@ -153,8 +160,9 @@ export default class Init extends Command {
             // Generate config
             console.log(chalk.cyan('⚙️  Generating configuration...'));
             await this.generateConfig(selectedIntegrations);
-            // Generate INSTRUCTIONS.md
+            // Generate INSTRUCTIONS.md and QUICKSTART.md
             await this.generateInstructions();
+            await this.generateQuickstart();
             // Generate commands for each selected integration
             console.log(chalk.cyan(`\n📝 Generating commands for ${selectedIntegrations.length} integration(s)...\n`));
             for (const integrationName of selectedIntegrations) {
@@ -553,8 +561,20 @@ 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;
     }
+    async 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=init.js.map

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
      */
@@ -168,6 +169,8 @@ For more information, run \`clavix --help\` in your terminal.
 
 This project uses Clavix for prompt improvement and PRD generation. The following slash commands are available:
 
+> **Command Format:** Commands shown with colon (\`:\`) format. Some tools use hyphen (\`-\`): Claude Code uses \`/clavix:improve\`, Cursor uses \`/clavix-improve\`. Your tool autocompletes the correct format.
+
 ### Prompt Optimization
 
 #### /clavix:improve [prompt]
@@ -184,7 +187,7 @@ Generate an optimized implementation task breakdown from your PRD. Creates a pha
 #### /clavix:implement
 Execute tasks or prompts with AI assistance. Auto-detects source: tasks.md (from PRD workflow) or prompts/ (from improve workflow). Supports automatic git commits and progress tracking.
 
-Use \`--latest\` to execute most recent prompt, \`--tasks\` to force task mode.
+Use \`--latest\` to implement most recent prompt, \`--tasks\` to force task mode.
 
 ### Session Management
 
@@ -194,6 +197,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 +215,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/core/template-assembler.d.ts

@@ -51,6 +51,8 @@ export declare class TemplateAssembler {
     hasIncludes(content: string): boolean;
     /**
      * Process all include markers in content
+     * @param content - The template content to process
+     * @param depth - Current nesting depth (for circular include protection)
      */
     private processIncludes;
     /**

package/dist/core/template-assembler.js

@@ -1,5 +1,15 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
+import { DataError } from '../types/errors.js';
+/**
+ * Maximum depth for nested {{INCLUDE:}} directives
+ * Prevents infinite loops from circular includes
+ */
+const MAX_INCLUDE_DEPTH = 10;
+/**
+ * Depth at which to log a warning about deep nesting
+ */
+const DEPTH_WARNING_THRESHOLD = 5;
 /**
  * TemplateAssembler - v4.0 Template Modularity System
  *
@@ -30,13 +40,13 @@ export class TemplateAssembler {
     async assembleTemplate(templatePath) {
         const fullPath = path.join(this.templatesBasePath, 'slash-commands', '_canonical', templatePath);
         const content = await this.loadFile(fullPath);
-        return this.processIncludes(content);
+        return this.processIncludes(content, 0);
     }
     /**
      * Assemble template from raw content string
      */
     async assembleFromContent(content) {
-        return this.processIncludes(content);
+        return this.processIncludes(content, 0);
     }
     /**
      * Check if a template contains include markers
@@ -46,8 +56,19 @@ export class TemplateAssembler {
     }
     /**
      * Process all include markers in content
+     * @param content - The template content to process
+     * @param depth - Current nesting depth (for circular include protection)
      */
-    async processIncludes(content) {
+    async processIncludes(content, depth) {
+        // Circular include protection
+        if (depth > MAX_INCLUDE_DEPTH) {
+            throw new DataError(`Maximum include depth (${MAX_INCLUDE_DEPTH}) exceeded`, 'Check for circular {{INCLUDE:}} references in templates');
+        }
+        // Warn about deep nesting
+        if (depth === DEPTH_WARNING_THRESHOLD) {
+            console.warn(`[TemplateAssembler] Warning: Include depth ${depth} reached. ` +
+                'Consider flattening template structure.');
+        }
         const includedComponents = [];
         const missingComponents = [];
         const variablesUsed = new Set();
@@ -86,9 +107,9 @@ export class TemplateAssembler {
                 processedContent = processedContent.replace(fullMatch, `<!-- MISSING COMPONENT: ${componentPath} -->`);
             }
         }
-        // Process nested includes (recursive)
+        // Process nested includes (recursive with depth tracking)
         if (this.hasIncludes(processedContent)) {
-            const nestedResult = await this.processIncludes(processedContent);
+            const nestedResult = await this.processIncludes(processedContent, depth + 1);
             processedContent = nestedResult.content;
             includedComponents.push(...nestedResult.includedComponents);
             missingComponents.push(...nestedResult.missingComponents);

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.
@@ -79,6 +80,8 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 ### Workflow Commands (Slash Commands)
 All workflows are executed via slash commands that AI agents read and follow:
 
+> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
+
 | Slash Command | Purpose |
 |---------------|---------|
 | `/clavix:improve` | Optimize prompts (auto-selects depth) |
@@ -87,6 +90,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:

package/dist/templates/instructions/QUICKSTART.md

@@ -0,0 +1,65 @@
+# Clavix Quick Reference
+
+## Commands at a Glance
+
+| Command | Purpose | Mode |
+|---------|---------|------|
+| `/clavix:improve` | Optimize a prompt with auto-depth | Planning |
+| `/clavix:prd` | Generate PRD via strategic questions | Planning |
+| `/clavix:plan` | Create task breakdown from PRD | Planning |
+| `/clavix:implement` | Execute tasks or prompts | Implementation |
+| `/clavix:start` | Begin conversational exploration | Planning |
+| `/clavix:summarize` | Extract requirements from conversation | Planning |
+| `/clavix:refine` | Update existing PRD or prompt | Planning |
+| `/clavix:verify` | Check implementation against requirements | Verification |
+| `/clavix:archive` | Move completed project to archive | Management |
+
+> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
+
+## Common Workflows
+
+**Quick optimization:**
+```
+/clavix:improve "your prompt here"
+  → /clavix:implement --latest
+```
+
+**Full planning cycle:**
+```
+/clavix:prd
+  → /clavix:plan
+  → /clavix:implement
+  → /clavix:verify
+  → /clavix:archive
+```
+
+**Exploratory approach:**
+```
+/clavix:start
+  → (conversation)
+  → /clavix:summarize
+  → /clavix:plan
+  → /clavix:implement
+```
+
+## Key Directories
+
+- `.clavix/outputs/` — Generated PRDs, tasks, prompts
+- `.clavix/outputs/prompts/` — Saved optimized prompts
+- `.clavix/outputs/archive/` — Archived completed projects
+- `.clavix/instructions/` — Detailed workflow documentation
+
+## Mode Boundaries
+
+- **Planning Mode** (improve, prd, plan, start, summarize, refine): NO code generation
+- **Implementation Mode** (implement): Code generation ALLOWED
+- **Verification Mode** (verify): Read-only checks
+- **Management Mode** (archive): File organization only
+
+## Getting Started
+
+1. Run `clavix init` to set up your project
+2. Use `/clavix:improve "your idea"` to optimize a prompt
+3. Use `/clavix:implement --latest` to implement it
+
+For detailed documentation, see `.clavix/instructions/` in your project.

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

@@ -326,9 +326,9 @@ Before considering this task complete, verify:
 
 ---
 
-## CHECKPOINT: Analysis Complete?
+**CHECKPOINT:** Analysis Complete
 
-**Before proceeding to save, verify you have output ALL of the following:**
+Before proceeding to save, verify you have output ALL of the following:
 
 **Standard Depth:**
 - [ ] **Intent Analysis** with type and confidence
@@ -349,9 +349,9 @@ Before considering this task complete, verify:
 
 ---
 
-## ⛔ SAVING CHECKPOINT (REQUIRED - DO NOT SKIP)
+**CHECKPOINT:** Saving Protocol (REQUIRED - DO NOT SKIP)
 
-**DO NOT output any "saved" message until you have COMPLETED and VERIFIED all save steps.**
+DO NOT output any "saved" message until you have COMPLETED and VERIFIED all save steps.
 
 This is a BLOCKING checkpoint. You cannot proceed to the final message until saving is verified.
 

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

@@ -252,11 +252,17 @@ mkdir -p .clavix/outputs/{sanitized-project-name}
 ```
 
 ### Step 5: Verify Files Were Created
-```bash
-ls .clavix/outputs/{project-name}/
-```
 
-**Expected output**:
+**Verification Protocol:**
+1. **Immediately after Write**, use Read tool to verify each file:
+   - Read `.clavix/outputs/{project-name}/full-prd.md`
+   - Confirm content matches what you wrote
+   - Read `.clavix/outputs/{project-name}/quick-prd.md`
+   - Confirm content matches what you wrote
+
+2. **If Read fails**: STOP and report error to user
+
+**Expected files**:
 - `full-prd.md`
 - `quick-prd.md`