clavix 5.5.1 → 5.5.2

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;
@@ -553,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:

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

@@ -0,0 +1,612 @@
+---
+name: "Clavix: Refine"
+description: Refine existing PRD or prompt through continued discussion
+---
+
+# Clavix: Refine Your Requirements
+
+Need to update your PRD or improve a saved prompt? This command lets you refine existing work without starting over.
+
+---
+
+## What This Does
+
+When you run `/clavix:refine`, I:
+1. **Detect available targets** - Find PRDs and saved prompts in your project
+2. **Ask what to refine** - PRD project or saved prompt?
+3. **Load existing content** - Read and understand current state
+4. **Enter refinement mode** - Discuss what you want to change
+5. **Update the files** - Save refined version with change history
+
+**I'm refining existing work, not creating new content from scratch.**
+
+---
+
+## CLAVIX MODE: Refinement
+
+**I'm in refinement mode. Updating existing requirements or prompts.**
+
+**What I'll do:**
+- Check for existing PRDs and prompts
+- Ask you what you want to refine
+- Load and display current content
+- Discuss changes with you
+- Update files with tracked changes
+- Flag what changed vs. what stayed the same
+
+**What I won't do:**
+- Write implementation code
+- Create new PRDs from scratch (use `/clavix:prd` for that)
+- Create new prompts from scratch (use `/clavix:improve` for that)
+- Make changes without user approval
+
+**I'm improving what exists, not building from scratch.**
+
+For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
+
+---
+
+## Self-Correction Protocol
+
+**DETECT**: If you find yourself doing any of these 6 mistake types:
+
+| Type | What It Looks Like |
+|------|--------------------|
+| 1. Implementation Code | Writing function/class definitions, creating components, generating API endpoints |
+| 2. Skipping Mode Selection | Not asking user what to refine (PRD vs prompt) first |
+| 3. Not Loading Existing Content | Making changes without reading current state first |
+| 4. Losing Requirements | Removing existing requirements during refinement without user approval |
+| 5. Not Tracking Changes | Failing to mark what was [ADDED], [MODIFIED], [REMOVED], [UNCHANGED] |
+| 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing workflows |
+
+**STOP**: Immediately halt the incorrect action
+
+**CORRECT**: Output:
+"I apologize - I was [describe mistake]. Let me return to refinement mode."
+
+**RESUME**: Return to the refinement workflow with proper mode selection and content loading.
+
+---
+
+## State Assertion (Required)
+
+**Before starting refinement, output:**
+```
+**CLAVIX MODE: Refinement**
+Mode: planning
+Purpose: Refining existing PRD or prompt
+Implementation: BLOCKED - I will refine requirements, not implement them
+```
+
+---
+
+## Instructions
+
+### Step 0: Detect Available Refinement Targets
+
+**CHECKPOINT:** Starting detection of refinement targets
+
+Use file system tools to check for:
+
+**PRD Projects:**
+```bash
+# Look for PRD files
+ls .clavix/outputs/*/mini-prd.md 2>/dev/null
+ls .clavix/outputs/*/quick-prd.md 2>/dev/null
+ls .clavix/outputs/*/full-prd.md 2>/dev/null
+```
+
+**Saved Prompts:**
+```bash
+# Look for saved prompts
+ls .clavix/outputs/prompts/*.md 2>/dev/null
+```
+
+**Record what was found:**
+- PRD projects found: [list project names]
+- Saved prompts found: [list prompt files]
+
+**CHECKPOINT:** Detection complete - found [N] PRD projects, [M] saved prompts
+
+---
+
+### Step 1: Ask User What to Refine
+
+Based on what was found, ask the user:
+
+**If both PRDs and prompts exist:**
+```markdown
+## What Would You Like to Refine?
+
+I found refinement targets in your project:
+
+**PRD Projects:**
+- [project-name] (mini-prd.md, tasks.md)
+- [other-project] (quick-prd.md)
+
+**Saved Prompts:**
+- [timestamp]-[name].md
+- [other-prompt].md
+
+**What would you like to refine?**
+1. **A PRD project** - Modify requirements, features, constraints
+2. **A saved prompt** - Improve and optimize a prompt
+
+Please let me know which type, and I'll show you the specific options.
+```
+
+**If only PRDs exist:**
+```markdown
+## What Would You Like to Refine?
+
+I found [N] PRD project(s) in your outputs:
+- [project-name] (has mini-prd.md, tasks.md)
+
+Would you like to refine this PRD? I can help you:
+- Add new features
+- Modify existing requirements
+- Adjust constraints or scope
+- Update technical requirements
+```
+
+**If only prompts exist:**
+```markdown
+## What Would You Like to Refine?
+
+I found [N] saved prompt(s):
+- [prompt-file-1].md
+- [prompt-file-2].md
+
+Would you like to refine one of these prompts? I can help you:
+- Make it more specific
+- Add constraints or context
+- Clarify the objective
+- Improve overall quality
+```
+
+**If nothing found:**
+```markdown
+## No Refinement Targets Found
+
+I couldn't find any existing PRDs or saved prompts to refine.
+
+**To create new content:**
+- `/clavix:prd` - Create a new PRD through guided questions
+- `/clavix:improve [prompt]` - Optimize and save a prompt
+- `/clavix:start` → `/clavix:summarize` - Extract requirements from conversation
+
+Once you've created content with these commands, you can use `/clavix:refine` to update it.
+```
+
+**CHECKPOINT:** User selected refinement type: [PRD/Prompt]
+
+---
+
+## PRD Refinement Workflow
+
+*Only follow this section if user selected PRD refinement*
+
+### Step 2a: Load Existing PRD
+
+Read the PRD file(s) for the selected project:
+```bash
+# Read the mini-prd or quick-prd
+cat .clavix/outputs/[project-name]/mini-prd.md
+```
+
+**CHECKPOINT:** Loaded PRD for project: [project-name]
+
+### Step 3a: Display Current Requirements Summary
+
+Present the current state to the user:
+
+```markdown
+## Current Requirements for [Project Name]
+
+### Objective
+[Current objective from PRD]
+
+### Core Features
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+### Technical Constraints
+- [Constraint 1]
+- [Constraint 2]
+
+### Scope
+**In Scope:** [What's included]
+**Out of Scope:** [What's excluded]
+
+---
+
+**What would you like to refine?**
+1. Add new features
+2. Modify existing features
+3. Change technical constraints
+4. Adjust scope (add/remove items)
+5. Update success criteria
+6. Something else
+```
+
+### Step 4a: Refine Through Discussion
+
+Enter conversational mode to understand what changes are needed:
+
+- Listen to what the user wants to change
+- Ask clarifying questions
+- Propose specific changes
+- Get user approval before modifying
+
+**Track changes with markers:**
+- `[ADDED]` - New requirement or feature
+- `[MODIFIED]` - Changed from original
+- `[REMOVED]` - Explicitly removed (with user approval)
+- `[UNCHANGED]` - Kept as-is
+
+### Step 5a: Generate Updated PRD
+
+After discussion, update the PRD file:
+
+**Use the Write tool to update** `.clavix/outputs/[project-name]/mini-prd.md`
+
+Add a "Refinement History" section at the bottom:
+
+```markdown
+---
+
+## Refinement History
+
+### [Date] - Refinement Session
+
+**Changes Made:**
+- [ADDED] [Description of what was added]
+- [MODIFIED] [What changed and how]
+- [REMOVED] [What was removed and why]
+
+**Reason:** [Brief explanation of why changes were made]
+```
+
+**CHECKPOINT:** Updated PRD with [N] changes
+
+### Step 6a: Notify About Tasks
+
+If tasks.md exists for this project:
+
+```markdown
+## Note: Tasks May Need Regeneration
+
+This project has a `tasks.md` file that was generated from the previous PRD version.
+
+After refining the PRD, you may want to regenerate tasks:
+- Run `/clavix:plan` to create an updated task breakdown
+- Or manually update tasks.md to reflect the changes
+
+**Changes that likely affect tasks:**
+- [List significant changes that impact implementation]
+```
+
+---
+
+## Prompt Refinement Workflow
+
+*Only follow this section if user selected Prompt refinement*
+
+### Step 2b: List Available Prompts
+
+If multiple prompts exist:
+```markdown
+## Available Prompts
+
+| # | File | Created | Size |
+|---|------|---------|------|
+| 1 | [filename].md | [date] | [lines] |
+| 2 | [filename].md | [date] | [lines] |
+
+**Which prompt would you like to refine?**
+Enter the number, or type `latest` to refine the most recent.
+```
+
+### Step 3b: Load Selected Prompt
+
+Read the prompt file:
+```bash
+cat .clavix/outputs/prompts/[selected-file].md
+```
+
+**CHECKPOINT:** Loaded prompt: [filename]
+
+### Step 4b: Display Current Prompt and Quality
+
+Present the current prompt to the user:
+
+```markdown
+## Current Prompt: [filename]
+
+[Display the prompt content]
+
+---
+
+**Quality Assessment:**
+- Clarity: [Score]
+- Specificity: [Score]
+- Completeness: [Score]
+- Actionability: [Score]
+
+**What would you like to change?**
+1. Clarify the objective
+2. Add more context or constraints
+3. Make it more specific
+4. Change the approach
+5. Other (describe what you want)
+```
+
+### Step 5b: Refine Through Discussion
+
+Enter conversational mode:
+- Understand what the user wants to improve
+- Suggest specific enhancements
+- Re-assess quality as changes are made
+
+### Step 6b: Run Quality Assessment
+
+After refinement, re-assess using the same 6 dimensions as `/clavix:improve`:
+- Clarity
+- Specificity
+- Context
+- Constraints
+- Actionability
+- Structure
+
+### Step 7b: Save Refined Prompt
+
+**Use the Write tool** to update the prompt file:
+
+Add refinement metadata to frontmatter (if present) or create new:
+
+```markdown
+---
+refined: [date]
+original_created: [original date]
+refinements: 1
+---
+
+[Refined prompt content]
+
+---
+
+## Refinement Summary
+
+**Before:** [Brief description of original]
+**After:** [Brief description of refined version]
+
+**Quality Score:**
+- Before: [X]/100
+- After: [Y]/100
+
+**Improvements Applied:**
+- [What was changed and why]
+```
+
+**CHECKPOINT:** Saved refined prompt to [filename]
+
+### Step 8b: Show Before/After Comparison
+
+```markdown
+## Prompt Refinement Complete
+
+**Quality Score Improvement:** [X] → [Y] (+[diff])
+
+**Key Changes:**
+| Aspect | Before | After |
+|--------|--------|-------|
+| Clarity | [score] | [score] |
+| Specificity | [score] | [score] |
+| ... | ... | ... |
+
+**Next Steps:**
+- Run `/clavix:implement --latest` to execute this prompt
+- Or continue refining with another `/clavix:refine` session
+```
+
+---
+
+## Integration Points
+
+**After refining a PRD:**
+- Run `/clavix:plan` to regenerate tasks based on updated requirements
+- Note that existing tasks.md may be outdated
+
+**After refining a prompt:**
+- Run `/clavix:implement --latest` to execute the refined prompt
+
+**Iterative refinement:**
+- You can run `/clavix:refine` multiple times
+- Each session adds to the refinement history
+- Changes are tracked cumulatively
+
+---
+
+## Examples
+
+### Example: Adding a Feature to PRD
+
+**User:** "/clavix:refine"
+
+**Agent:** "I found 1 PRD project: 'user-dashboard'. Would you like to refine it?"
+
+**User:** "Yes, I want to add dark mode support."
+
+**Agent:**
+```markdown
+## Adding to [user-dashboard] PRD
+
+**Current features:**
+- User profile display
+- Activity feed
+- Notifications panel
+
+**Proposed addition:**
+- [ADDED] Dark mode toggle with system preference detection
+- [ADDED] Theme persistence across sessions
+- [MODIFIED] All UI components must support both themes
+
+Does this capture what you want to add?
+```
+
+### Example: Changing PRD Constraints
+
+**User:** "Actually, we need to support mobile now too."
+
+**Agent:**
+```markdown
+## Modifying Technical Constraints
+
+**Previous constraints:**
+- Desktop-only (1024px minimum)
+- Chrome/Firefox/Safari support
+
+**Updated constraints:**
+- [MODIFIED] Responsive design: 320px to 1920px
+- [ADDED] Mobile-first approach
+- [ADDED] Touch interaction support
+- [UNCHANGED] Chrome/Firefox/Safari support
+- [ADDED] iOS Safari and Chrome mobile support
+
+This changes scope significantly. Should I also update the success criteria?
+```
+
+### Example: Making a Prompt More Specific
+
+**User:** "/clavix:refine"
+
+**Agent:** "I found 2 saved prompts. Which would you like to refine?"
+
+**User:** "The API integration one."
+
+**Agent:**
+```markdown
+## Current Prompt Assessment
+
+"Build an API integration for our system."
+
+**Quality Scores:**
+- Clarity: 40/100 (too vague)
+- Specificity: 30/100 (no details)
+- Completeness: 20/100 (missing critical info)
+
+**What would you like to specify?**
+1. Which API to integrate?
+2. What operations are needed?
+3. Authentication requirements?
+4. Error handling expectations?
+```
+
+**User:** "It's the Stripe API for payments."
+
+**Agent:**
+```markdown
+## Refined Prompt
+
+"Integrate Stripe API for payment processing:
+- Support one-time payments and subscriptions
+- Handle webhook events for payment status updates
+- Store payment methods securely using Stripe tokens
+- Implement retry logic for failed charges
+- Generate receipts and send confirmation emails
+
+Technical: Use Stripe Node.js SDK, handle PCI compliance through Stripe Elements."
+
+**Quality Scores (After):**
+- Clarity: 85/100 (+45)
+- Specificity: 90/100 (+60)
+- Completeness: 80/100 (+60)
+```
+
+### Example: Reducing PRD Scope
+
+**User:** "We need to cut scope. Remove the analytics feature."
+
+**Agent:**
+```markdown
+## Scope Reduction
+
+**Removing from scope:**
+- [REMOVED] Analytics dashboard
+- [REMOVED] Usage metrics tracking
+- [REMOVED] Export to CSV feature
+
+**Keeping:**
+- [UNCHANGED] Core user management
+- [UNCHANGED] Notification system
+- [UNCHANGED] Settings page
+
+**Impact:**
+- Estimated effort reduction: ~30%
+- Dependencies affected: None (analytics was standalone)
+
+I'll update the PRD and add this to the refinement history. Confirm?
+```
+
+---
+
+## Agent Transparency (v5.5)
+
+### Agent Manual (Universal Protocols)
+{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
+
+### CLI Reference
+{{INCLUDE:agent-protocols/cli-reference.md}}
+
+### Workflow State Detection
+{{INCLUDE:agent-protocols/state-awareness.md}}
+
+---
+
+## Workflow Navigation
+
+**You are here:** Refine (Update existing PRD or prompt)
+
+**Common workflows:**
+- **PRD refinement**: `/clavix:refine` → update PRD → `/clavix:plan` → regenerate tasks
+- **Prompt refinement**: `/clavix:refine` → improve prompt → `/clavix:implement --latest`
+- **Iterative updates**: `/clavix:refine` → `/clavix:refine` → ... (multiple passes)
+
+**Related commands:**
+- `/clavix:prd` - Create new PRD from scratch (not refinement)
+- `/clavix:improve` - Create new optimized prompt (not refinement)
+- `/clavix:plan` - Generate tasks from PRD
+- `/clavix:implement` - Execute tasks or prompts
+
+---
+
+## Troubleshooting
+
+### Issue: No refinement targets found
+**Cause**: No PRDs or prompts have been created yet
+**Solution**:
+- Use `/clavix:prd` to create a PRD
+- Use `/clavix:improve [prompt]` to create and save a prompt
+- Use `/clavix:start` → `/clavix:summarize` to extract from conversation
+
+### Issue: Can't find specific project
+**Cause**: Project name doesn't match or files moved
+**Solution**:
+- Check `.clavix/outputs/` directory structure
+- Ensure mini-prd.md or quick-prd.md exists in project folder
+- Project names are case-sensitive
+
+### Issue: Changes lost after refinement
+**Cause**: Overwrote without tracking changes
+**Solution**:
+- Always use change markers: [ADDED], [MODIFIED], [REMOVED], [UNCHANGED]
+- Include Refinement History section
+- Review changes with user before saving
+
+### Issue: tasks.md out of sync with refined PRD
+**Cause**: Normal - tasks were generated from previous PRD version
+**Solution**:
+- Run `/clavix:plan` to regenerate tasks
+- Or manually update tasks.md
+- Previous progress markers may need adjustment

package/dist/utils/agent-error-messages.d.ts

@@ -82,5 +82,30 @@ export declare class AgentErrorMessages {
      * Used by: implement workflow when marking already-done task
      */
     static taskAlreadyCompleted(taskId: string): string;
+    /**
+     * Error: Template not found
+     * Used by: template-loader.ts, commands generating slash commands
+     */
+    static templateNotFound(templateName: string, searchPath?: string): string;
+    /**
+     * Error: Adapter/integration not found
+     * Used by: agent-manager.ts, init.ts
+     */
+    static adapterNotFound(adapterName: string, availableAdapters?: string[]): string;
+    /**
+     * Error: Configuration loading failed
+     * Used by: init.ts, update.ts when .clavix/config.json is invalid
+     */
+    static configLoadFailed(configPath: string, reason?: string): string;
+    /**
+     * Error: Update command failed
+     * Used by: update.ts when template regeneration fails
+     */
+    static updateFailed(reason: string): string;
+    /**
+     * Error: Diagnostic check failed
+     * Used by: diagnose.ts when health check identifies issues
+     */
+    static diagnosticFailed(issues: string[]): string;
 }
 //# sourceMappingURL=agent-error-messages.d.ts.map

package/dist/utils/agent-error-messages.js

@@ -191,5 +191,73 @@ export class AgentErrorMessages {
             '  3. Check if this was intended\n\n' +
             'No action needed unless forced.');
     }
+    /**
+     * Error: Template not found
+     * Used by: template-loader.ts, commands generating slash commands
+     */
+    static templateNotFound(templateName, searchPath) {
+        const pathInfo = searchPath ? `\nSearch path: ${searchPath}` : '';
+        return (`Template not found: ${templateName}${pathInfo}\n\n` +
+            'Agent recovery options:\n' +
+            "  1. Run 'clavix update' to regenerate templates\n" +
+            '  2. Check if Clavix is installed correctly\n' +
+            '  3. Verify template name is spelled correctly\n\n' +
+            'After recovery, retry the command.');
+    }
+    /**
+     * Error: Adapter/integration not found
+     * Used by: agent-manager.ts, init.ts
+     */
+    static adapterNotFound(adapterName, availableAdapters) {
+        const adapterList = availableAdapters
+            ? '\n\nAvailable adapters:\n' + availableAdapters.map((a) => `  • ${a}`).join('\n')
+            : '';
+        return (`Adapter not found: ${adapterName}${adapterList}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Check adapter name is spelled correctly\n' +
+            "  2. Run 'clavix diagnose' to see available integrations\n" +
+            '  3. Adapter may have been removed or renamed\n\n' +
+            'Use a valid adapter name and retry.');
+    }
+    /**
+     * Error: Configuration loading failed
+     * Used by: init.ts, update.ts when .clavix/config.json is invalid
+     */
+    static configLoadFailed(configPath, reason) {
+        const reasonInfo = reason ? `\nReason: ${reason}` : '';
+        return (`Failed to load configuration: ${configPath}${reasonInfo}\n\n` +
+            'Agent recovery options:\n' +
+            "  1. Run 'clavix init' to regenerate configuration\n" +
+            '  2. Check .clavix/config.json syntax is valid JSON\n' +
+            '  3. Remove .clavix/ and reinitialize\n\n' +
+            'After fixing configuration, retry the command.');
+    }
+    /**
+     * Error: Update command failed
+     * Used by: update.ts when template regeneration fails
+     */
+    static updateFailed(reason) {
+        return (`Update failed: ${reason}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Check Clavix is installed correctly: clavix --version\n' +
+            '  2. Verify write permissions in project directory\n' +
+            "  3. Try removing .clavix/ and running 'clavix init'\n\n" +
+            'Fix the underlying issue and retry.');
+    }
+    /**
+     * Error: Diagnostic check failed
+     * Used by: diagnose.ts when health check identifies issues
+     */
+    static diagnosticFailed(issues) {
+        const issueList = issues.map((issue) => `  • ${issue}`).join('\n');
+        return ('Diagnostic check identified issues:\n\n' +
+            issueList +
+            '\n\n' +
+            'Agent recovery options:\n' +
+            "  1. Run 'clavix update' to fix template issues\n" +
+            "  2. Run 'clavix init' to reinitialize configuration\n" +
+            '  3. Check file permissions in project directory\n\n' +
+            'Address issues above and rerun diagnose.');
+    }
 }
 //# sourceMappingURL=agent-error-messages.js.map

package/dist/utils/integration-selector.d.ts

@@ -1,8 +1,20 @@
 import { AgentManager } from '../core/agent-manager.js';
+/**
+ * AGENTS.md is always enabled by default.
+ * It provides universal agent guidance that all AI tools can read.
+ */
+export declare const MANDATORY_INTEGRATION = "agents-md";
 /**
  * Interactive integration selection utility
  * Displays multi-select checkbox for all available integrations
  * Used by both init and config commands
+ *
+ * Note: AGENTS.md is always enabled and not shown in selection
  */
 export declare function selectIntegrations(agentManager: AgentManager, preSelected?: string[]): Promise<string[]>;
+/**
+ * Ensures AGENTS.md is always included in the final integration list.
+ * Call this after selectIntegrations() to enforce mandatory integrations.
+ */
+export declare function ensureMandatoryIntegrations(integrations: string[]): string[];
 //# sourceMappingURL=integration-selector.d.ts.map

package/dist/utils/integration-selector.js

@@ -1,8 +1,15 @@
 import inquirer from 'inquirer';
+/**
+ * AGENTS.md is always enabled by default.
+ * It provides universal agent guidance that all AI tools can read.
+ */
+export const MANDATORY_INTEGRATION = 'agents-md';
 /**
  * Interactive integration selection utility
  * Displays multi-select checkbox for all available integrations
  * Used by both init and config commands
+ *
+ * Note: AGENTS.md is always enabled and not shown in selection
  */
 export async function selectIntegrations(agentManager, preSelected = []) {
     const { selectedIntegrations } = await inquirer.prompt([
@@ -31,8 +38,8 @@ export async function selectIntegrations(agentManager, preSelected = []) {
                 { name: 'Roocode (.roo/clavix/)', value: 'roocode' },
                 { name: 'Windsurf (.windsurf/rules/)', value: 'windsurf' },
                 new inquirer.Separator(),
-                new inquirer.Separator('=== Universal Adapters ==='),
-                { name: 'AGENTS.md (Universal)', value: 'agents-md' },
+                new inquirer.Separator('=== Optional Universal Adapters ==='),
+                // Note: AGENTS.md is always enabled (not shown here)
                 { name: 'GitHub Copilot (.github/copilot-instructions.md)', value: 'copilot-instructions' },
                 { name: 'OCTO.md (Universal)', value: 'octo-md' },
                 { name: 'WARP.md (Universal)', value: 'warp-md' },
@@ -57,4 +64,14 @@ export async function selectIntegrations(agentManager, preSelected = []) {
     ]);
     return selectedIntegrations;
 }
+/**
+ * Ensures AGENTS.md is always included in the final integration list.
+ * Call this after selectIntegrations() to enforce mandatory integrations.
+ */
+export function ensureMandatoryIntegrations(integrations) {
+    if (!integrations.includes(MANDATORY_INTEGRATION)) {
+        return [MANDATORY_INTEGRATION, ...integrations];
+    }
+    return integrations;
+}
 //# sourceMappingURL=integration-selector.js.map

package/dist/utils/toml-templates.js

@@ -1,3 +1,4 @@
+import { DataError } from '../types/errors.js';
 /**
  * Parse TOML-based slash command templates (Gemini/Qwen) and extract metadata.
  * Ensures the resulting prompt body does not include duplicated frontmatter.
@@ -10,13 +11,13 @@ export function parseTomlSlashCommand(content, templateName, integrationName) {
     const descriptionMatch = normalized.match(/^\s*description\s*=\s*(['"])(.*?)\1\s*$/m);
     const promptHeaderMatch = normalized.match(/^\s*prompt\s*=\s*"""/m);
     if (!promptHeaderMatch || promptHeaderMatch.index === undefined) {
-        throw new Error(`Template ${templateName}.toml for ${integrationName} is missing a prompt = """ ... """ block.`);
+        throw new DataError(`Template ${templateName}.toml for ${integrationName} is missing a prompt = """ ... """ block.`, 'Check the template file format. TOML templates require prompt = """...""" syntax.');
     }
     const bodyStart = promptHeaderMatch.index + promptHeaderMatch[0].length;
     const bodyRemainder = normalized.slice(bodyStart);
     const closingIndex = bodyRemainder.indexOf('"""');
     if (closingIndex === -1) {
-        throw new Error(`Template ${templateName}.toml for ${integrationName} does not terminate its prompt = """ ... """ block.`);
+        throw new DataError(`Template ${templateName}.toml for ${integrationName} does not terminate its prompt = """ ... """ block.`, 'Add closing """ to the prompt block.');
     }
     let promptBody = bodyRemainder.slice(0, closingIndex);
     const promptLines = promptBody.split('\n');

package/dist/utils/version.d.ts

@@ -2,11 +2,6 @@
  * Version utility for Clavix
  * Centralizes version reading from package.json
  */
-/**
- * Get the current Clavix version from package.json
- * Returns '0.0.0' if package.json cannot be read
- */
-export declare function getVersion(): Promise<string>;
 /**
  * Get version synchronously (for use in type definitions)
  * Falls back to hardcoded version if file cannot be read

package/dist/utils/version.js

@@ -7,20 +7,6 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-/**
- * Get the current Clavix version from package.json
- * Returns '0.0.0' if package.json cannot be read
- */
-export async function getVersion() {
-    try {
-        const packageJsonPath = path.join(__dirname, '../../package.json');
-        const packageJson = await fs.readJson(packageJsonPath);
-        return packageJson.version || '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 /**
  * Get version synchronously (for use in type definitions)
  * Falls back to hardcoded version if file cannot be read

package/oclif.manifest.json

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

package/package.json

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