v5.5.2 - /clavix:refine Command & Architecture Improvements

What's New

/clavix:refine Command

New slash command for refining existing PRDs and prompts:

• Auto-detects available refinement targets (PRDs and saved prompts)
• Change tracking with [ADDED], [MODIFIED], [REMOVED], [UNCHANGED] markers
• Before/after quality comparison for prompts
• Refinement history tracking in PRD files
• Integration guidance for next steps (plan regeneration, implementation)

Mandatory AGENTS.md Integration

Universal agent guidance is now always enabled:

• AGENTS.md automatically included in all installations
• Removed from user selection (handled internally)
• Users informed during init: "AGENTS.md is always enabled to provide universal agent guidance"

New AgentErrorMessages Methods

Extended error messaging for better diagnostics:

• templateNotFound() - When template files are missing
• adapterNotFound() - When adapter lookup fails
• configLoadFailed() - When configuration parsing fails
• updateFailed() - When update command encounters issues
• diagnosticFailed() - When diagnose command finds problems

Changes

Error Handling Consistency

Replaced generic Error throws with typed DataError:

• agents-md-generator.ts, octo-md-generator.ts, warp-md-generator.ts
• copilot-instructions-generator.ts, instructions-generator.ts
• toml-templates.ts

Constants Consolidation

Cleaned up src/constants.ts:

• Removed 11 unused constants
• Kept only CLAVIX_BLOCK_START and CLAVIX_BLOCK_END
• Updated all imports to use constants instead of hardcoded values

CONTRIBUTING.md Updates

Added explicit architecture boundaries:

• "Explicitly Forbidden Features" section with 4 rejected proposals
• Clear explanations for WHY certain features don't fit the architecture
• Guidance on what TO do instead of forbidden patterns

Fixes

Documentation Accuracy

• Updated TESTING.md: Changed 100% to 70%+ (actual thresholds)
• Updated getting-started.md: Added summarize outputs documentation
• Updated docs/commands.md with full refine command documentation

---

Full Changelog: v5.5.1...v5.5.2

v5.5.0 - Adapter Architecture Refactor

What's Changed

Major Changes

• Adapter Architecture Refactor - Unified adapter system using config-driven factory pattern:
  • Migrated 12 simple adapters to UniversalAdapter class with ADAPTER_CONFIGS registry
  • Kept dedicated classes for special adapters: ClaudeCodeAdapter (doc injection), GeminiAdapter, QwenAdapter, LlxprtAdapter (TOML format)
  • Significantly reduced code duplication while maintaining all functionality

Error Handling Improvements

• Template assembly failures now throw DataError instead of silent warnings
• Standardized all console.warn calls to use logger.warn utility
• Fixed deprecated escapeRegex wrapper in base-adapter.ts

Removed

• Code Consolidation: Deleted 12 redundant adapter source files + 12 test files (24 files total)
• Documentation Cleanup: Removed v4-era configuration references, deleted docs/archive/ directory

Fixed

• Updated test files to use dynamic adapter paths instead of hardcoded directories
• Fixed adapter contract tests to work with new factory pattern
• All 998 tests pass with 75.82% coverage

Full Changelog: https://github.com/mike-sobolev/clavix/compare/v5.4.0...v5.5.0

v5.4.0 - Documentation Cleanup & Template Improvements

What's Changed

Documentation Cleanup

• Removed outdated /docs/clavix-intelligence.md (referenced removed pattern system)
• Updated /docs/guides/workflows.md for v5 architecture (no more clavix fast/clavix deep)
• Updated /docs/how-it-works.md to explain agentic-first architecture
• Fixed /src/templates/instructions/README.md component references

Template Improvements

• Added Self-Correction Protocol to implement.md, verify.md, archive.md
• Added State Assertion blocks for mode enforcement
• Fixed improve.md naming ("Optimize" → "Improve") and softened defensive tone

Dead Code Removal

• Removed preserveSessions from PreferencesConfig (sessions removed in v5.3.0)
• Removed sessionNotFound() from AgentErrorMessages
• Removed session directory references from error messages

Terminology Standardization

• "Optimize" → "Improve" in template naming and documentation
• "provider" → "integration" in code comments and variables
• "execute" → "implement" in agent templates

Test Updates

• Updated test factory to match current ClavixConfig shape
• Fixed 4 test files to match v5.4 changes

Full Changelog: v5.3.1...v5.4.0

v5.3.1 - Cline Integration Cleanup Fix

Fixed

• Cline integration cleanup bug - When deselecting Cline during clavix init reconfiguration and choosing "Clean up", the .clinerules/workflows/clavix/ subdirectory is now properly removed. Previously, removeAllCommands() only removed files, ignoring subdirectories.

---

Full Changelog: v5.3.0...v5.3.1

v5.3.0

v5.3.0 - Config Elimination & Adapter Registry

BREAKING CHANGES

• Session persistence removed - .clavix/sessions/ directory no longer created
• clavix config eliminated - Use clavix init instead

Added

• Adapter registry infrastructure - Config-driven adapter system (adapter-registry.ts, universal-adapter.ts)
• Init reconfiguration menu - Three options when re-running init:
  • "Reconfigure integrations"
  • "Update existing"
  • "Cancel"
• Consistency tests - New test suite verifies removed commands are properly cleaned up
• Template manifest - Documents all reusable components

Changed

• Config functionality merged into clavix init
• Legacy cleanup utility marked deprecated for v6.0.0

Removed

• clavix config command
• Orphaned template components (decision-rules.md, error-handling.md)
• Session references from all templates

Tests

• 1496 tests passing
• Added 39 update.ts tests
• Added 14 init reconfiguration tests
• Added removed-commands consistency test

v5.2.1 - Diagnose Command & DRY Refactor

Highlights

New clavix diagnose Command

Full diagnostic report for troubleshooting installations:

• Version check
• Directory structure validation
• Config integrity verification
• Integration status with command counts
• Template integrity check
• Summary with recommendations

DRY Architecture Refactor

• TomlFormattingAdapter base class eliminates ~140 lines of duplication across Gemini, Qwen, and LLXPRT adapters
• DocInjector utility reduces repetition in AgentsMd, OctoMd, WarpMd, and CopilotInstructions generators
• Removed ~90 lines of vestigial v4 config types

Bug Fixes (v5.2.1)

Fixed 3 bugs where clavix diagnose showed incorrect warnings after successful clavix init:

• No longer expects .clavix/commands/ directory (commands go to adapter-specific directories)
• Recognizes doc generator integrations (agents-md, octo-md, warp-md, copilot-instructions) as valid
• Removed misleading "No slash commands installed" check

Other Changes

• Slash commands now shown in --help output
• Feature matrix added to README
• Removed unimplemented -g/--global flag from clavix config

---

Full Changelog: v5.1.1...v5.2.1

v5.1.1 - Agent Manual & Project Cleanup

What's New

Template Improvements

• NEW: Consolidated AGENT_MANUAL.md component for all slash command templates
  • Universal agent protocols (error handling, decision rules)
  • Agentic-first architecture guidance
  • Output verification protocol
  • Mode boundaries reference
• Updated all 8 canonical templates to use the new AGENT_MANUAL.md

Code Cleanup

• Removed deprecated ProviderFeatures type alias
• Fixed ESLint warnings in error-utils.ts (proper OclifError typing)
• Updated agent-error-messages.ts (removed references to deleted commands)

Documentation

• Created docs/commands/verify.md
• Deleted orphaned docs (list.md, show.md, task-complete.md)
• Updated CHANGELOG.md
• Added .gitkeep files with descriptions

Dependencies

• Removed unused packages: handlebars, json5, uuid

Validation

• ✅ All 1297 tests passing (55 test suites)
• ✅ Build passes with consistency validation
• ✅ Lint passes with 0 warnings

Installation

npm install -g clavix@5.1.1

Or update existing installation:

clavix update

v5.1.0 - Execute → Implement Consolidation

What's New

Execute → Implement Consolidation

/clavix:execute has been removed. All functionality is now in /clavix:implement with auto-detection:

/clavix:implement
    │
    ├─► Checks tasks.md → Task Implementation Mode
    │
    └─► Checks prompts/ → Prompt Execution Mode

New flags:

• --tasks - Force task mode
• --prompt <id> - Execute specific prompt
• --latest - Execute most recent prompt

Template Cleanup

• Removed 18 unused component files
• Deleted deprecated docs (fast.md, deep.md, prompts.md, execute.md)
• Net reduction: ~2,000 lines

Breaking Changes

• /clavix:execute removed → use /clavix:implement
• Workflow count: 9 → 8 canonical templates

Migration

Replace any /clavix:execute usage:

# Old
/clavix:execute --latest

# New
/clavix:implement --latest

Stats

• 50 files changed
• 1406 tests passing
• All consistency checks pass

v5.0.0 - Agentic-First Architecture

Clavix v5.0.0 - Agentic-First Architecture

Major release with complete architecture redesign for lean, template-driven workflows.

Breaking Changes

This release removes ~50,000 lines of TypeScript code. The intelligence layer and most CLI commands are gone.

Removed CLI Commands

• clavix fast / clavix deep → Use /clavix:improve slash command
• clavix execute → Use /clavix:execute slash command
• clavix prompts → Prompts are now .md files with frontmatter
• clavix prd / clavix plan / clavix implement → Use slash commands
• clavix analyze / clavix verify / clavix archive → Use slash commands

Remaining CLI Commands (4 total)

• clavix init - Initialize Clavix in a project
• clavix update - Update templates after package update
• clavix config - Manage configuration
• clavix version - Show version

What's New

Agentic-First Architecture

• Templates are the product - AI agents execute workflows by reading markdown templates
• No TypeScript runs during workflows - Agents use native tools (Read, Write, Edit, Glob, Bash)
• Prompt files use frontmatter - No more .index.json, metadata lives in each .md file

Prompt File Format (v5)

---
id: std-20251127-143022-a3f2
timestamp: 2025-11-27T14:30:22Z
executed: false
originalPrompt: "the user's original prompt"
depthUsed: standard
---

# Improved Prompt
<optimized content>

Migration from v4

1. Run clavix update to get new templates
2. Use slash commands instead of CLI commands
3. Existing prompts in .index.json format will need manual migration

Stats

• Removed: ~50,000 lines of code
• Tests: 1,406 passing
• CLI Commands: 4 (down from 15+)

See CHANGELOG.md for full details.

v4.12.0 - Honest Optimization Release

Honest Optimization Release

Removed boilerplate patterns and improved documentation honesty. Clavix is "just prompt improvement" - no magic, no hype.

Pattern Library Cleanup

Removed 7 boilerplate patterns that generated static output instead of improving prompts:

Removed Pattern	Reason
AlternativePhrasingGenerator	Generated static suggestions, not prompt improvements
EdgeCaseIdentifier	Listed generic edge cases, didn't enhance the prompt
ValidationChecklistCreator	Created boilerplate checklists, not prompt-specific
AssumptionExplicitizer	Added generic assumption lists
ScopeDefiner	Generated templated scope statements
ErrorToleranceEnhancer	Added boilerplate error handling text
PrerequisiteIdentifier	Listed generic prerequisites

Pattern count reduced from 27 to 20 patterns - all remaining patterns actively improve prompt quality.

Documentation Honesty

• Removed "Clavix Intelligence™" branding - it's prompt improvement, not AI/ML
• Created /docs/philosophy.md - explains agent-first design and honest positioning
• Created /docs/guides/choosing-workflow.md - practical guidance for workflow selection
• Updated /docs/how-it-works.md - clear explanation of what Clavix actually does

Configurable Thresholds

Escalation thresholds are now configurable via .clavix/config.json:

{
  "intelligence": {
    "escalation": {
      "comprehensiveAbove": 75,
      "standardFloor": 60,
      "intentConfidenceMin": 50
    }
  }
}

Legacy Command Cleanup

clavix init and clavix update now automatically remove deprecated /clavix:fast and /clavix:deep slash command files when upgrading from older versions.

Install

npm install -g clavix@4.12.0

---

Full changelog: https://github.com/ClavixDev/Clavix/blob/main/CHANGELOG.md