clavix 4.11.1 → 4.11.2

package/dist/templates/instructions/README.md

@@ -4,103 +4,84 @@ This directory contains the complete instruction set for AI agents consuming Cla
 
 ---
 
-## 📐 Documentation Architecture
+## 📐 Documentation Architecture (v4.11)
 
 ```
 Canonical Templates (SOURCE OF TRUTH)
   src/templates/slash-commands/_canonical/
-  ├── fast.md, deep.md, prd.md
-  ├── start.md, summarize.md
-  ├── plan.md, implement.md, execute.md
-  └── archive.md, prompts.md
-    ↓ (copied during clavix init)
-Instruction Files (AUTO-GENERATED)
+  ├── improve.md          - Unified prompt optimization (standard + comprehensive)
+  ├── prd.md              - PRD generation via Socratic questions
+  ├── start.md            - Conversational mode entry
+  ├── summarize.md        - Extract requirements from conversation
+  ├── plan.md             - Task breakdown from PRD
+  ├── implement.md        - Execute tasks with progress tracking
+  ├── execute.md          - Run saved prompts
+  ├── verify.md           - Post-implementation verification
+  └── archive.md          - Archive completed projects
+    ↓ (referenced by)
+Component Templates (REUSABLE BUILDING BLOCKS)
+  src/templates/slash-commands/_components/
+  ├── agent-protocols/    - Self-correction, state awareness, decision rules
+  ├── sections/           - Quality dimensions, patterns, escalation factors
+  └── troubleshooting/    - Mode confusion, triage escalation
+    ↓ (copied during clavix init/update)
+User Instructions
   .clavix/instructions/
-  ├── workflows/         - Complete workflows (COPIED from canonical)
-  ├── core/             - Foundational concepts (static)
-  └── troubleshooting/  - Common issues (static)
-    ↓ (reference)
-Generic Connectors (THIN WRAPPERS)
-  src/templates/agents/
-  ├── agents.md          - Generic agents
-  ├── octo.md           - Octofriend-specific
-  ├── copilot-instructions.md - GitHub Copilot
-  └── warp.md           - Warp AI
+  ├── core/              - Foundational concepts (clavix-mode, verification)
+  └── troubleshooting/   - Common issues and fixes
+    ↓ (referenced by)
+Integration Adapters (THIN WRAPPERS)
+  src/templates/integrations/
+  ├── claude-code/       - Claude Code adapter
+  ├── cursor/            - Cursor adapter
+  ├── windsurf/          - Windsurf adapter
+  └── ... (22 integrations total)
 ```
 
 ---
 
 ## 🎯 Core Principles
 
-### 1. Single Source of Truth
+### 1. Canonical Templates = Single Source of Truth
 
-**Canonical templates** (`src/templates/slash-commands/_canonical/`) are the definitive reference:
-- Complete workflow descriptions
-- Official command behavior
-- Authoritative patterns and examples
+**Canonical templates** (`src/templates/slash-commands/_canonical/`) define authoritative behavior:
+- Complete workflow descriptions with all steps
+- Official command behavior and output formats
+- Patterns, examples, and edge cases
 - NEVER modified for size/brevity - they define the standard
 
-**Rule:** When canonical and instruction files conflict, canonical wins.
+**Rule:** When in doubt, canonical templates are correct.
 
-### 2. Agent-Optimized Instructions
+### 2. Component Templates = DRY Building Blocks
 
-**Instruction files** (`src/templates/instructions/`) are derived from canonical templates but optimized for AI agent consumption:
-- Must match canonical workflows 100% in substance
-- Can reorganize for better agent comprehension
-- Add explicit checkpoints, self-correction checks, troubleshooting
-- Include "Common Mistakes" sections with wrong/right examples
-- Expand on ambiguous points from canonical
+**Component templates** (`src/templates/slash-commands/_components/`) provide reusable sections:
+- `agent-protocols/` - Self-correction, state detection, decision rules
+- `sections/` - Quality dimensions, pattern visibility, escalation factors
+- `troubleshooting/` - Error recovery and mode confusion handling
 
-**Rule:** Instruction files implement canonical, never contradict it.
+**Rule:** Shared content lives in components, not duplicated across canonicals.
 
-### 3. Thin Generic Connectors
+### 3. Integration Adapters = Platform-Specific Wrappers
 
-**Generic connector files** (`src/templates/agents/`) are minimal wrappers:
-- Reference instruction files, don't duplicate them
-- Platform-specific guidance ONLY (model switching, tool limitations, etc.)
-- Brief workflow overview + standard workflow (PRD → Plan → Implement → Archive)
-- Command quick reference table
-- Common mistakes specific to platform
+**Integration adapters** (`src/templates/integrations/`) provide minimal platform wrappers:
+- Reference canonical templates, don't duplicate content
+- Platform-specific formatting and tool usage
+- Command format transformation (colon vs hyphen separators)
+- Model-specific guidance (context limits, tool availability)
 
-**Target sizes:**
-- agents.md: 4-7K (generic, no platform features)
-- octo.md: 7-10K (Octofriend has unique features)
-- copilot-instructions.md: 5-7K (GitHub Copilot integration)
-- warp.md: 5-7K (Warp AI-specific)
-
-**Rule:** If it's in an instruction file, don't duplicate it in a connector file.
+**Rule:** If it's in canonical, don't duplicate in adapter.
 
 ---
 
 ## 📂 Directory Structure
 
-### `/workflows/` - Step-by-Step Workflows
-
-Complete, executable workflows with explicit steps:
-
-| File | Purpose | Key Sections |
-|------|---------|--------------|
-| `start.md` | Conversational mode entry | Questions, complexity tracking, mode transitions |
-| `summarize.md` | Extract requirements from conversation | Pre-validation, extraction, file creation, optimization |
-| `fast.md` | Quick prompt optimization | Intent detection, quality assessment, smart triage |
-| `deep.md` | Comprehensive analysis | Strategic scope, alternatives, validation, edge cases, risks |
-| `prd.md` | PRD generation via Socratic questions | 5-question sequence, validation criteria, file-saving protocol |
-
-**Pattern:** Each workflow file includes:
-- CLAVIX PLANNING MODE block (clarifies planning vs implementation)
-- Complete workflow steps with checkpoints
-- Self-correction checks
-- Common mistakes (wrong/right examples)
-- Troubleshooting references
-- Integration with other workflows
-
 ### `/core/` - Foundational Concepts
 
 Cross-workflow patterns and principles:
 
 | File | Purpose | Key Content |
 |------|---------|-------------|
-| `clavix-mode.md` | Planning vs implementation distinction | Mode table, standard workflow, command categorization |
+| `clavix-mode.md` | Planning vs implementation distinction | Mode table, command categorization, standard workflow |
 | `file-operations.md` | File creation patterns | Write tool usage, verification steps, error handling |
 | `verification.md` | Checkpoint patterns | Self-correction triggers, validation approaches |
 
@@ -124,125 +105,116 @@ Problem → Solution guides:
 
 ---
 
-## 🔄 Maintenance Workflow
+## 📋 Quick Reference
 
-### When Adding New Workflow
+### Standard Workflow
 
-1. **Create canonical template** in `src/templates/slash-commands/_canonical/`
-   - Complete workflow description
-   - All steps, examples, edge cases
-   - This is the official reference
+All workflows follow this progression:
 
-2. **NO NEED to create instruction file** - It's auto-copied during init
-   - During `clavix init`, canonical templates are automatically copied to `.clavix/instructions/workflows/`
-   - User projects get fresh copy on init/update
-   - **Single source of truth:** Only maintain canonical template
+```
+PRD Creation → Task Planning → Implementation → Verification → Archive
+```
 
-3. **Update generic connectors** in `src/templates/agents/` (if needed)
-   - Add table reference to new workflow
-   - Update workflow detection keywords
-   - DO NOT duplicate workflow steps
+| Phase | Command | Output | Mode |
+|-------|---------|--------|------|
+| **Planning** | `/clavix:prd` or `/clavix:start` | `full-prd.md` + `quick-prd.md` | PLANNING |
+| **Task Prep** | `/clavix:plan` | `tasks.md` | PLANNING |
+| **Implementation** | `/clavix:implement` | Executed code | IMPLEMENTATION |
+| **Verification** | `/clavix:verify` | Verification report | VERIFICATION |
+| **Completion** | `/clavix:archive` | Archived project | MANAGEMENT |
 
-4. **Update this README** if new pattern/principle introduced
+### Command Mode Mapping
 
-### When Modifying Existing Workflow
+| Command | Mode | Implement? |
+|---------|------|------------|
+| `/clavix:start` | Planning | ✗ NO |
+| `/clavix:summarize` | Planning | ✗ NO |
+| `/clavix:improve` | Planning | ✗ NO |
+| `/clavix:prd` | Planning | ✗ NO |
+| `/clavix:plan` | Planning | ✗ NO |
+| `/clavix:implement` | Implementation | ✓ YES |
+| `/clavix:execute` | Implementation | ✓ YES |
+| `/clavix:verify` | Verification | Context-dependent |
+| `/clavix:archive` | Management | ✗ NO |
 
-1. **Update canonical template** - This is source of truth
-2. **Users run `clavix update`** - Refreshes `.clavix/instructions/workflows/` from canonical
-3. **Test:** Verify `clavix update` propagates changes correctly
-4. **No manual duplication needed** - InstructionsGenerator copies from canonical automatically
+### Agent-Only Commands (No Slash Command)
 
-### When Reporting Verbosity Issues
+| CLI Command | Purpose | Invoked By |
+|-------------|---------|------------|
+| `clavix analyze` | Internal prompt analysis | `improve` workflow |
+| `clavix task-complete` | Mark task done | `implement` workflow |
 
-**Bloat checklist:**
-1. Is canonical template duplicated in instruction file? → Remove from instruction, reference canonical
-2. Is instruction file duplicated in connector file? → Remove from connector, reference instruction
-3. Is workflow description inline in connector? → Remove, add table reference to instruction file
-4. Are "Common Mistakes" duplicated across files? → Keep in instruction file only
-5. Is command reference table too detailed? → Condense to single-line purpose
+---
 
-**Size targets:**
-- Canonical templates: 10-20K (complete reference, no size limit)
-- Instruction files: 10-18K (agent-optimized, comprehensive)
-- Generic connectors: 4-10K (thin wrappers)
+## 🔄 Maintenance Workflow
 
----
+### When Adding New Workflow
 
-## 🧠 Design Philosophy
+1. **Create canonical template** in `src/templates/slash-commands/_canonical/`
+   - Complete workflow description
+   - All steps, examples, edge cases
+   - Include CLAVIX MODE header if planning-only
 
-### Why Three Layers?
+2. **Create CLI command** in `src/cli/commands/`
+   - Implement the command behavior
+   - Ensure template and CLI match
 
-**Layer 1: Canonical Templates**
-- **Audience:** CLI implementation, human developers, official documentation
-- **Purpose:** Define authoritative behavior
-- **Constraint:** Complete and accurate, no brevity requirement
+3. **Update tests** in `tests/consistency/`
+   - Add command to `cli-template-parity.test.ts` categories
+   - Update any affected consistency tests
 
-**Layer 2: Instruction Files**
-- **Audience:** AI agents (all platforms)
-- **Purpose:** Executable guidance with self-correction
-- **Constraint:** Must match canonical, optimized for agent comprehension
+4. **Run validation**: `npm run validate:consistency`
 
-**Layer 3: Generic Connectors**
-- **Audience:** Platform-specific agents (Copilot, Octofriend, Warp, generic)
-- **Purpose:** Minimal platform-specific wrapper + references
-- **Constraint:** Keep thin, reference instruction files, platform-unique guidance only
+### When Modifying Existing Workflow
 
-### Why Not Just One File?
+1. **Update canonical template** - This is the source of truth
+2. **Update CLI if behavior changed**
+3. **Run validation**: `npm run validate:consistency`
+4. **Users run `clavix update`** - Refreshes their local instructions
 
-**Problems with single-file approach:**
-1. **Duplication:** Same workflow described 4+ times (canonical + 3 platforms)
-2. **Maintenance burden:** Update one workflow = edit 4+ files
-3. **Size bloat:** Each platform file becomes 15-20K
-4. **Inconsistency:** Descriptions drift apart over time
-5. **Confusion:** Agent sees multiple versions, unclear which is authoritative
+### Preventing the "Half-Update" Problem
 
-**Benefits of three-layer hierarchy:**
-1. **DRY principle:** Write workflow once (instruction file), reference everywhere
-2. **Single source of truth:** Canonical → Instruction → Connector flow
-3. **Platform focus:** Connector files focus on platform-specific value (model switching, tool limitations)
-4. **Maintainability:** Fix bug in one instruction file, all platforms benefit
-5. **Clarity:** Agent knows where to look - instruction file for workflow, connector for platform quirks
+The v4.11.2 release introduced validation to catch incomplete updates:
 
----
+```bash
+# Run before committing
+npm run validate:consistency
 
-## 📋 Quick Reference Tables
+# Checks performed:
+# - No legacy command references (fast, deep commands removed in v4.11)
+# - All CLI commands have templates (if required)
+# - All templates have CLI implementations
+# - No deprecated version references
+# - Mode enforcement headers present
+```
 
-### Standard Workflow
+---
 
-All workflows follow this progression:
+## 🧠 Design Philosophy
 
-```
-PRD Creation → Task Planning → Implementation → Archive
-```
+### Why Canonical Templates?
 
-| Phase | Command | Output | Mode |
-|-------|---------|--------|------|
-| **Planning** | `clavix prd` or conversational | `full-prd.md` + `quick-prd.md` | PLANNING |
-| **Task Prep** | `clavix plan` | `tasks.md` | PLANNING (Pre-Implementation) |
-| **Implementation** | `clavix implement` | Executed code | IMPLEMENTATION |
-| **Completion** | `clavix archive` | Archived project | Management |
+**Canonical templates solve the documentation drift problem:**
+- Single authoritative source for workflow behavior
+- Agents can trust template instructions match CLI behavior
+- Updates propagate through validation, not manual duplication
+- Clear ownership: canonical defines, adapters reference
 
-### Mode Distinction
+### Why Component Templates?
 
-| Command | Mode | Implement? |
-|---------|------|------------|
-| `/clavix:start` | Planning | ✗ NO |
-| `/clavix:summarize` | Planning | ✗ NO |
-| `/clavix:fast` | Planning | ✗ NO |
-| `/clavix:deep` | Planning | ✗ NO |
-| `/clavix:prd` | Planning | ✗ NO |
-| `/clavix:plan` | Planning (Pre-Implementation) | ✗ NO |
-| `/clavix:implement` | Implementation | ✓ YES |
-| `/clavix:execute` | Implementation | ✓ YES |
-| `/clavix:task-complete` | Implementation | ✓ YES |
+**Components prevent duplication:**
+- Quality dimensions defined once, used in improve.md
+- Agent protocols shared across all planning workflows
+- Troubleshooting sections reusable across contexts
+- Pattern visibility documented centrally
 
-### File Size Expectations
+### Why Integration Adapters?
 
-| File Type | Size Range | Line Range | Purpose |
-|-----------|-----------|------------|---------|
-| Canonical Template | 10-20K | 300-600 lines | Complete reference (no limit) |
-| Instruction File | 10-18K | 350-650 lines | Agent-executable workflows |
-| Generic Connector | 4-10K | 150-300 lines | Thin wrapper + platform-specific |
+**Adapters handle platform differences:**
+- Command format: `/clavix:improve` vs `/clavix-improve`
+- Tool availability: Some platforms lack filesystem access
+- Context limits: Different token limits per platform
+- Model guidance: Platform-specific best practices
 
 ---
 
@@ -253,10 +225,9 @@ PRD Creation → Task Planning → Implementation → Archive
 **Root cause:** Agent didn't recognize planning mode boundary
 
 **Fix:**
-1. Check instruction file has CLAVIX PLANNING MODE block at top
-2. Verify "DO NOT IMPLEMENT" warnings present and clear
-3. Add self-correction check: "Check 1: Am I Implementing?"
-4. Reference `troubleshooting/jumped-to-implementation.md`
+1. Check canonical template has CLAVIX MODE header at top
+2. Verify "DO NOT IMPLEMENT" warnings present
+3. Reference `troubleshooting/jumped-to-implementation.md`
 
 ### "Agent skipped file creation"
 
@@ -264,48 +235,50 @@ PRD Creation → Task Planning → Implementation → Archive
 
 **Fix:**
 1. Add explicit step-by-step file creation section
-2. Include "Step N: Verify Files Were Created" with ls command
-3. Add common mistake: "Skipping file creation"
-4. Reference `troubleshooting/skipped-file-creation.md`
+2. Include verification step with file listing
+3. Reference `troubleshooting/skipped-file-creation.md`
 
-### "Generic connector file too large (>10K)"
+### "Legacy command references found"
 
-**Root cause:** Duplicating instruction file content
+**Root cause:** Template not updated during v4.11 migration
 
 **Fix:**
-1. Identify duplicated workflow descriptions
-2. Replace with table reference to instruction file
-3. Keep only platform-specific guidance (model switching, tool limitations, etc.)
-4. Condense CLI reference table (one line per command)
-5. Remove detailed workflow explanations (link to instruction file instead)
+1. Run `npm run validate:consistency` to find all occurrences
+2. Replace legacy fast/deep commands with `clavix improve`
+3. Replace "fast mode"/"deep mode" with "standard depth"/"comprehensive depth"
+4. Update any navigation references
 
-### "Instruction file doesn't match canonical"
+### "Template doesn't match CLI behavior"
 
-**Root cause:** Manual edit to instruction file without checking canonical
+**Root cause:** CLI changed without updating canonical template
 
 **Fix:**
-1. Read canonical template: `src/templates/slash-commands/_canonical/<workflow>.md`
-2. Compare with instruction file: `src/templates/instructions/workflows/<workflow>.md`
-3. Ensure substance matches 100%
-4. Reorganization for agent clarity is OK, contradicting canonical is NOT
+1. Read canonical template in `src/templates/slash-commands/_canonical/`
+2. Compare with actual CLI behavior
+3. Update canonical template to match CLI
+4. Run `npm run validate:consistency`
+5. Update `cli-template-parity.test.ts` if needed
 
 ---
 
-## 📚 Additional Resources
+## 📚 Key Files Reference
+
+### Canonical Templates (Start Here)
+- `improve.md` - Unified prompt optimization (v4.11)
+- `prd.md` - PRD generation workflow
+- `implement.md` - Task execution workflow
 
-**Related documentation:**
-- `src/templates/slash-commands/_canonical/README.md` - Canonical template guidelines
-- `src/templates/agents/README.md` - Generic connector patterns (if exists)
-- `CONTRIBUTING.md` - General contribution guidelines
-- `ARCHITECTURE.md` - Overall Clavix architecture
+### Agent Protocols
+- `_components/agent-protocols/self-correction.md` - Mistake detection
+- `_components/agent-protocols/state-awareness.md` - Workflow state tracking
+- `_components/agent-protocols/decision-rules.md` - Decision logic
 
-**Key files to read first:**
-- `core/clavix-mode.md` - Understand planning vs implementation
-- `workflows/fast.md` - See complete workflow pattern
-- `../agents/octo.md` - See thin connector example (post-v3.6.1)
+### Validation
+- `scripts/validate-consistency.ts` - TypeScript ↔ Template validator
+- `tests/consistency/cli-template-parity.test.ts` - CLI-Template mapping tests
 
 ---
 
-**Last updated:** v3.6.1 (November 2025)
+**Last updated:** v4.11.2 (November 2025)
 
-**Maintainers:** Ensure this README stays synchronized with actual instruction hierarchy.
+**Validation:** Run `npm run validate:consistency` before committing changes.

package/dist/templates/instructions/core/clavix-mode.md

@@ -6,7 +6,7 @@ Clavix has **two distinct modes** based on the command type:
 
 ### CLAVIX PLANNING MODE (Requirements & Documentation)
 
-**Commands:** `/clavix:start`, `/clavix:summarize`, `/clavix:fast`, `/clavix:deep`, `/clavix:prd`
+**Commands:** `/clavix:start`, `/clavix:summarize`, `/clavix:improve`, `/clavix:prd`
 
 **Your role:**
 - Ask questions about requirements
@@ -40,8 +40,7 @@ Clavix has **two distinct modes** based on the command type:
 |---------|------|------------|
 | `/clavix:start` | Planning | ✗ NO |
 | `/clavix:summarize` | Planning | ✗ NO |
-| `/clavix:fast` | Planning | ✗ NO |
-| `/clavix:deep` | Planning | ✗ NO |
+| `/clavix:improve` | Planning | ✗ NO |
 | `/clavix:prd` | Planning | ✗ NO |
 | `/clavix:plan` | Planning (Pre-Implementation) | ✗ NO |
 | `/clavix:implement` | Implementation | ✓ YES |
@@ -108,7 +107,7 @@ Clavix has **two distinct modes** based on the command type:
 **User runs:** `/clavix:implement` or `/clavix:execute`
 → **You are in IMPLEMENTATION MODE** - write code
 
-**User runs:** `/clavix:prd` or `/clavix:fast` or `/clavix:start`
+**User runs:** `/clavix:prd` or `/clavix:improve` or `/clavix:start`
 → **You are in PLANNING MODE** - gather requirements, don't implement
 
 ---

package/dist/templates/instructions/core/verification.md

@@ -281,42 +281,40 @@ If workflow isn't proceeding as expected, check:
 
 ---
 
-### Quick Improvement (/clavix:fast)
+### Prompt Improvement (/clavix:improve)
 
 ```markdown
 **Checkpoints to include:**
 
-1. After analysis:
+1. After triage:
+   **CHECKPOINT:** Triage complete - [standard/comprehensive] depth selected
+
+2. After analysis:
    **CHECKPOINT:** Analyzed prompt - identified [N] improvement areas
 
-2. After optimization:
+3. After optimization:
    **CHECKPOINT:** Generated optimized prompt with [N] enhancements
 
-3. After file creation:
-   **CHECKPOINT:** Saved prompt to .clavix/outputs/prompts/fast/[id].md
+4. After file creation:
+   **CHECKPOINT:** Saved prompt to .clavix/outputs/prompts/[id].md
 
-4. After verification:
+5. After verification:
    **CHECKPOINT:** File verified - prompt saved successfully
 ```
 
----
-
-### Deep Analysis (/clavix:deep)
+**For Comprehensive Depth (`/clavix:improve --comprehensive`):**
 
 ```markdown
-**Checkpoints to include:**
+**Additional checkpoints:**
 
-1. After initial analysis:
-   **CHECKPOINT:** Completed deep analysis - generated [N] alternative phrasings
+1. After alternative analysis:
+   **CHECKPOINT:** Generated [N] alternative phrasings
 
 2. After edge case analysis:
    **CHECKPOINT:** Identified [M] edge cases and potential issues
 
-3. After file creation:
-   **CHECKPOINT:** Created comprehensive analysis document
-
-4. After verification:
-   **CHECKPOINT:** All outputs verified - deep analysis complete
+3. After validation checklist:
+   **CHECKPOINT:** Created comprehensive analysis with validation checklist
 ```
 
 ---

package/dist/templates/instructions/troubleshooting/jumped-to-implementation.md

@@ -54,7 +54,7 @@ Let me return to asking clarifying questions about your requirements instead.
 Agent should:
 1. **Return** to asking clarifying questions (if in `/clavix:start`)
 2. **Return** to extracting requirements (if in `/clavix:summarize`)
-3. **Return** to analyzing prompts (if in `/clavix:fast` or `/clavix:deep`)
+3. **Return** to analyzing prompts (if in `/clavix:improve`)
 4. **Return** to generating PRD (if in `/clavix:prd`)
 
 **NOT** continue with implementation.

package/dist/templates/instructions/troubleshooting/skipped-file-creation.md

@@ -11,7 +11,7 @@ Agent completed a Clavix workflow but didn't create the expected output files. C
 - Agent says "files created" but they don't exist in `.clavix/outputs/`
 - Agent provides content in chat instead of using Write tool
 - Agent completes `/clavix:summarize` but no mini-prd.md, original-prompt.md, or optimized-prompt.md files
-- Agent finishes `/clavix:fast` or `/clavix:deep` but no saved prompt file
+- Agent finishes `/clavix:improve` but no saved prompt file
 - Agent generates PRD content but no PRD.md or PRD-quick.md files
 
 ---
@@ -262,23 +262,23 @@ Should show all three files.
 
 ---
 
-### Test Scenario 2: Fast Improvement
+### Test Scenario 2: Prompt Improvement
 
 **Setup:**
 ```markdown
-User: /clavix:fast [prompt]
+User: /clavix:improve [prompt]
 ```
 
 **Expected behavior:**
-- Agent analyzes prompt
+- Agent analyzes prompt with triage
 - Agent generates optimized version
-- Agent creates .clavix/outputs/prompts/fast/ directory
-- Agent writes fast-YYYYMMDD-HHMM.md file
+- Agent creates .clavix/outputs/prompts/ directory
+- Agent writes prompt file with timestamp ID
 - Agent verifies file created
 
 **Test:**
 ```bash
-ls -la .clavix/outputs/prompts/fast/
+ls -la .clavix/outputs/prompts/
 ```
 
 Should show saved prompt file.

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

@@ -176,7 +176,7 @@ I tell you:
 
 ## Prompts Are Separate
 
-Fast/deep prompts from `/clavix:fast` and `/clavix:deep` are stored separately in `.clavix/outputs/prompts/`.
+Optimized prompts from `/clavix:improve` are stored separately in `.clavix/outputs/prompts/`.
 
 **Prompts are NOT archived with PRD projects.**
 

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

@@ -357,7 +357,7 @@ The generated `tasks.md` will look like:
 **Agent recovery**:
 1. Read the PRD to assess detail level
 2. If PRD is vague:
-   - Suggest: "Let's improve the PRD with `/clavix:deep` first"
+   - Suggest: "Let's improve the PRD with `/clavix:improve --comprehensive` first"
    - Then regenerate tasks with `clavix plan --overwrite`
 3. If PRD is detailed but tasks are high-level:
    - Manually break each task into 3-5 concrete sub-tasks

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

@@ -310,8 +310,8 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 **Common workflows:**
 - **Full planning workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
-- **From deep mode**: `/clavix:deep` → (strategic scope detected) → `/clavix:prd`
-- **Quick to strategic**: `/clavix:fast` → (realizes complexity) → `/clavix:prd`
+- **From improve mode**: `/clavix:improve` → (strategic scope detected) → `/clavix:prd`
+- **Quick to strategic**: `/clavix:improve` → (realizes complexity) → `/clavix:prd`
 
 **Related commands:**
 - `/clavix:plan` - Generate task breakdown from PRD (next step)

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

@@ -194,7 +194,7 @@ After the conversational session, `/clavix:summarize` will:
 **Related commands:**
 - `/clavix:summarize` - Extract and optimize conversation (typical next step)
 - `/clavix:prd` - Switch to Clavix Planning Mode for structured PRD generation
-- `/clavix:fast` or `/clavix:deep` - Direct prompt improvement instead of conversation
+- `/clavix:improve` - Direct prompt improvement instead of conversation
 
 ## Note
 

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

@@ -405,7 +405,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
 **Related commands:**
 - `/clavix:start` - Begin conversational exploration (typical previous step)
 - `/clavix:plan` - Generate tasks from extracted mini-PRD (next step)
-- `/clavix:fast` or `/clavix:deep` - Further optimize the extracted prompt
+- `/clavix:improve` - Further optimize the extracted prompt
 
 ## Example
 

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

@@ -241,9 +241,9 @@ Failed checks are normal. They just mean something needs a bit more work.
 
 ---
 
-## Fast Mode vs Deep Mode
+## Standard vs Comprehensive Depth
 
-### If You Used Deep Mode (`/clavix:deep`)
+### If You Used Comprehensive Depth (`/clavix:improve --comprehensive`)
 
 Your prompt already has a detailed checklist. I'll use that.
 
@@ -253,9 +253,9 @@ Your prompt already has a detailed checklist. I'll use that.
 - Potential risks identified
 - Specific verification criteria
 
-### If You Used Fast Mode (`/clavix:fast`)
+### If You Used Standard Depth (`/clavix:improve`)
 
-Fast mode doesn't create detailed checklists, so I'll generate one based on what you were building.
+Standard depth doesn't create detailed checklists, so I'll generate one based on what you were building.
 
 **What you get:**
 - Basic checks based on what you asked for
@@ -263,8 +263,8 @@ Fast mode doesn't create detailed checklists, so I'll generate one based on what
 - Common sense verifications
 
 **You'll see:**
-> "This was a fast mode prompt, so I'm creating a basic checklist.
-> For more thorough verification next time, use /clavix:deep"
+> "This was a standard depth prompt, so I'm creating a basic checklist.
+> For more thorough verification next time, use /clavix:improve --comprehensive"
 
 ---
 
@@ -371,7 +371,7 @@ I generate different checklists based on what you're building:
 **Where you are:** Verification (checking your work)
 
 **How you got here:**
-1. `/clavix:deep` or `/clavix:fast` → Optimized your prompt
+1. `/clavix:improve` → Optimized your prompt
 2. `/clavix:execute` → Implemented the requirements
 3. **`/clavix:verify`** → Now checking it works (you are here)
 
@@ -381,7 +381,7 @@ I generate different checklists based on what you're building:
 
 **Related commands:**
 - `/clavix:execute` - Run the implementation (previous step)
-- `/clavix:deep` - Get comprehensive checklist next time
+- `/clavix:improve --comprehensive` - Get comprehensive checklist next time
 - `/clavix:archive` - Archive when done (next step)
 
 ---

package/dist/templates/slash-commands/_components/agent-protocols/decision-rules.md

@@ -7,11 +7,11 @@ These rules define deterministic agent behavior. Follow exactly - no interpretat
 ```
 IF quality < 60%:
   IF (completeness < 50%) OR (clarity < 50%) OR (actionability < 50%):
-    → ACTION: Strongly recommend /clavix:deep
-    → SAY: "Quality is [X]%. Deep mode strongly recommended for: [low dimensions]"
+    → ACTION: Strongly recommend comprehensive depth
+    → SAY: "Quality is [X]%. Comprehensive depth strongly recommended for: [low dimensions]"
   ELSE:
-    → ACTION: Suggest /clavix:deep
-    → SAY: "Quality is [X]%. Consider deep mode for better results."
+    → ACTION: Suggest comprehensive depth
+    → SAY: "Quality is [X]%. Consider comprehensive depth for better results."
 
 IF quality >= 60% AND quality < 80%:
   → ACTION: Proceed with optimization
@@ -46,19 +46,19 @@ IF confidence < 50%:
 
 ```
 IF escalation_score >= 75:
-  → ACTION: Strongly recommend deep mode
+  → ACTION: Strongly recommend comprehensive depth
   → SHOW: Top 3 contributing factors
 
 IF escalation_score 60-74:
-  → ACTION: Recommend deep mode
+  → ACTION: Recommend comprehensive depth
   → SHOW: Primary contributing factor
 
 IF escalation_score 45-59:
-  → ACTION: Suggest deep mode as option
-  → SAY: "Deep mode available for more thorough analysis"
+  → ACTION: Suggest comprehensive depth as option
+  → SAY: "Comprehensive depth available for more thorough analysis"
 
 IF escalation_score < 45:
-  → ACTION: Fast mode sufficient
+  → ACTION: Standard depth sufficient
   → NO escalation mention
 ```
 
@@ -120,7 +120,7 @@ IF pattern not applicable to intent:
 IF pattern applicable but skipped:
   → EXPLAIN: "Skipped [pattern] because [reason]"
 
-DEEP MODE ONLY:
+COMPREHENSIVE DEPTH ONLY:
   → MUST include alternatives (2-3)
   → MUST include validation checklist
   → MUST include edge cases
@@ -129,15 +129,15 @@ DEEP MODE ONLY:
 ### Rule 8: Mode Transition Decision
 
 ```
-IF user requests /clavix:fast but quality < 50%:
-  → ACTION: Warn and suggest deep
-  → SAY: "Quality is [X]%. Fast mode may be insufficient."
+IF user requests standard depth but quality < 50%:
+  → ACTION: Warn and suggest comprehensive
+  → SAY: "Quality is [X]%. Standard depth may be insufficient."
   → ALLOW: User can override and proceed
 
-IF user in /clavix:deep but prompt is simple (quality > 85%):
+IF user requests comprehensive depth but prompt is simple (quality > 85%):
   → ACTION: Note efficiency
-  → SAY: "Prompt is already high quality. Fast mode would suffice."
-  → CONTINUE: With deep analysis anyway
+  → SAY: "Prompt is already high quality. Standard depth would suffice."
+  → CONTINUE: With comprehensive analysis anyway
 
 IF strategic keywords detected (3+ architecture/security/scalability):
   → ACTION: Suggest PRD mode

package/dist/templates/slash-commands/_components/agent-protocols/self-correction.md

@@ -17,8 +17,8 @@
 - Providing optimization without quality analysis
 - Jumping directly to improved prompt without showing scores
 
-### Mistake Type 3: Wrong Mode Selection
-- Not suggesting `/clavix:deep` when quality scores are low
+### Mistake Type 3: Wrong Depth Selection
+- Not suggesting comprehensive depth when quality scores are low
 - Not recommending `/clavix:prd` for strategic decisions
 - Ignoring triage indicators and escalation factors
 
@@ -27,8 +27,8 @@
 - Skipping patterns without explanation
 - Not showing which patterns were applied
 
-### Mistake Type 5: Missing Validation (Deep Mode)
-- Not generating validation checklist in deep mode
+### Mistake Type 5: Missing Validation (Comprehensive Depth)
+- Not generating validation checklist in comprehensive depth
 - Not identifying edge cases
 - Not providing alternative approaches
 

package/dist/templates/slash-commands/_components/agent-protocols/state-assertion.md

@@ -17,8 +17,7 @@ Implementation: [BLOCKED|ALLOWED]
 
 | Mode | Type | Implementation | Purpose |
 |------|------|----------------|---------|
-| /clavix:fast | planning | BLOCKED | Prompt optimization |
-| /clavix:deep | planning | BLOCKED | Comprehensive prompt analysis |
+| /clavix:improve | planning | BLOCKED | Prompt optimization (smart depth selection) |
 | /clavix:prd | planning | BLOCKED | PRD development |
 | /clavix:plan | planning | BLOCKED | Task breakdown generation |
 | /clavix:start | planning | BLOCKED | Requirements gathering |
@@ -37,9 +36,9 @@ Implementation: [BLOCKED|ALLOWED]
 
 **Planning Mode (Implementation BLOCKED):**
 ```
-**CLAVIX MODE: Fast Optimization**
+**CLAVIX MODE: Improve**
 Mode: planning
-Purpose: Optimizing user prompt with Clavix Intelligence™
+Purpose: Optimizing user prompt with Clavix Intelligence
 Implementation: BLOCKED - I will analyze and improve the prompt, not implement it
 ```
 

package/dist/templates/slash-commands/_components/agent-protocols/state-awareness.md

@@ -50,7 +50,7 @@ Always output current state when starting a workflow:
 NO_PROJECT:
   → /clavix:prd creates PRD_EXISTS
   → /clavix:start + /clavix:summarize creates PRD_EXISTS
-  → /clavix:fast or /clavix:deep creates prompt (not PRD_EXISTS)
+  → /clavix:improve creates prompt (not PRD_EXISTS)
 
 PRD_EXISTS:
   → /clavix:plan creates TASKS_EXIST

package/dist/templates/slash-commands/_components/troubleshooting/mode-confusion.md

@@ -41,6 +41,6 @@
 1. Ask user to clarify current intent
 2. Check last Clavix command run
 3. Mode determination:
-   - `/clavix:fast`, `/clavix:deep`, `/clavix:prd`, `/clavix:start`, `/clavix:summarize`, `/clavix:plan` → PLANNING
+   - `/clavix:improve`, `/clavix:prd`, `/clavix:start`, `/clavix:summarize`, `/clavix:plan` → PLANNING
    - `/clavix:implement`, `/clavix:execute` → IMPLEMENTATION
 4. If still unclear, default to PLANNING and ask for clarification

package/dist/templates/slash-commands/_components/troubleshooting/triage-escalation.md

@@ -1,26 +1,26 @@
-### Issue: Triage keeps recommending deep mode
+### Issue: Triage keeps recommending comprehensive depth
 
 **Cause**: Prompt has low quality scores + multiple secondary indicators
 
 **Solution**:
-- Accept the recommendation - deep mode will provide better analysis
-- OR improve prompt manually before running fast mode again
+- Accept the recommendation - comprehensive depth will provide better analysis
+- OR improve prompt manually before running with standard depth again
 - Check which quality dimension is scoring low and address it
 
-### Issue: Can't determine if prompt is complex enough for deep mode
+### Issue: Can't determine if prompt is complex enough for comprehensive depth
 
 **Cause**: Borderline quality scores or unclear content quality
 
 **Solution**:
-- Err on side of fast mode first
-- If output feels insufficient, escalate to `/clavix:deep`
+- Err on side of standard depth first
+- If output feels insufficient, escalate to `/clavix:improve --comprehensive`
 - Use triage as guidance, not absolute rule
 
 ### Issue: Improved prompt still feels incomplete
 
-**Cause**: Fast mode only applies basic optimizations
+**Cause**: Standard depth only applies basic optimizations
 
 **Solution**:
-- Use `/clavix:deep` for alternative approaches, edge cases, and validation checklists
+- Use `/clavix:improve --comprehensive` for alternative approaches, edge cases, and validation checklists
 - OR use `/clavix:prd` if strategic planning is needed
-- Fast mode is for quick cleanup, not comprehensive analysis
+- Standard depth is for quick cleanup, not comprehensive analysis

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "4.11.1",
+  "version": "4.11.2",
   "description": "Clavix Intelligence™ for AI coding. Automatically optimizes prompts with intent detection, quality assessment, and adaptive patterns—no framework to learn. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,8 @@
     "test:watch": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --watch",
     "test:coverage": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --coverage",
     "test:changed": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --changedSince=HEAD~1 --passWithNoTests",
+    "test:parity": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest tests/consistency/cli-template-parity.test.ts",
+    "test:consistency": "NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest tests/consistency/",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "format": "prettier --write \"src/**/*.ts\"",