clavix 4.11.2 → 5.0.0

package/README.md

@@ -1,10 +1,10 @@
 # Clavix
-> **Clavix Intelligence™** for AI coding. Transform rough ideas into production-ready prompts with automatic quality optimization—no framework to learn.
+> Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.
 
 ## Table of contents
 - [Why Clavix?](#why-clavix)
 - [How It Works](#how-it-works)
-- [Providers](#providers)
+- [Supported AI Tools](#supported-ai-tools)
 - [Quickstart](#quickstart)
 - [Full documentation](#full-documentation)
 
@@ -12,105 +12,117 @@
 
 | Version | Highlights | Details |
 | --- | --- | --- |
-| **v3.6.1** (Latest) | Documentation hierarchy & verbosity reduction | [Changelog](CHANGELOG.md#361---2025-11-24) |
-| **v3.6.0** | Enhanced generic connector instructions | [Changelog](CHANGELOG.md#360---2025-11-24) |
-| **v3.5.0** | "Providers" → "Integrations" terminology | [Changelog](CHANGELOG.md#350---2025-01-24) |
-| **v3.4.0** | Provider categorization fixes | [Changelog](CHANGELOG.md#340---2025-11-24) |
+| **v5.0.0** (Latest) | Agentic-first architecture - lean template delivery | [Changelog](CHANGELOG.md#500---2025-01-27) |
+| **v4.12.0** | Final v4 release with full CLI commands | [Changelog](docs/archive/v4-changelog.md) |
 
-**Requirements:** Node.js ≥ 16.0.0 (ESM support required)
+**Requirements:** Node.js >= 18.0.0
 
 ## Why Clavix?
-Better prompts lead to better code. Clavix automatically detects what you're trying to do and applies the right optimization patterns—no framework to learn, no methodology to master. Just describe what you want, and Clavix makes it AI-ready.
 
-**What makes Clavix v3.0 unique:**
-- **95%+ Intent Detection Accuracy** - Weighted keyword scoring, phrase-based detection, and negation handling
-- **6 Production-Ready Optimization Patterns** - Automatically applied based on intent and quality assessment
-- **Zero Learning Curve** - Works with your natural language, adapts to your style
-- **Universal Integration** - Supports 20+ AI coding assistants with native slash commands
+Better prompts lead to better code. Clavix provides **markdown templates** that teach AI agents how to:
+- **Optimize prompts** - Transform rough ideas into structured, AI-ready prompts
+- **Create PRDs** - Generate comprehensive requirements documents through guided questions
+- **Plan implementations** - Break down PRDs into phased task lists
+- **Track progress** - Manage task completion with optional git commits
+
+**No framework to learn.** Just describe what you want, and your AI agent follows the Clavix templates to structure it properly.
 
 Learn more in [docs/why-clavix.md](docs/why-clavix.md).
 
 ## How It Works
-Clavix uses **Clavix Intelligence™** (v3.0+) to automatically:
-- **Detect intent** - 95%+ accuracy with weighted scoring, phrase detection, and context analysis
-- **Assess quality** - Evaluates across 5 dimensions: Clarity, Efficiency, Structure, Completeness, Actionability
-- **Apply patterns** - 6 optimization patterns automatically selected and prioritized for your specific need
-- **Generate output** - Production-ready prompts optimized for AI coding assistants
 
-**The magic happens automatically**—no frameworks to learn, no manual analysis required. Just describe what you want in plain language, and Clavix transforms it into an AI-ready prompt using battle-tested optimization patterns.
+Clavix v5 follows an **agentic-first architecture**:
 
-## Providers
+1. **You run `clavix init`** - Sets up `.clavix/` directory with slash command templates
+2. **You invoke a slash command** - Like `/clavix:improve` in Claude Code or Cursor
+3. **Your AI agent reads the template** - The markdown file contains all instructions
+4. **The agent follows the instructions** - Using its native tools (Write, Read, Edit, etc.)
+5. **Output is saved** - To `.clavix/outputs/` for future reference
 
-| Category | Providers |
-| --- | --- |
-| IDE & editor extensions | Cursor · Windsurf · Kilocode · Roocode · Cline |
-| CLI agents | Claude Code · Droid CLI · CodeBuddy CLI · OpenCode · Gemini CLI · Qwen Code · LLXPRT · Amp · Crush CLI · Codex CLI · Augment CLI |
-| Universal adapters | AGENTS.md · GitHub Copilot · OCTO.md · WARP.md |
+**No TypeScript code executes during slash command usage.** The templates are the product - they instruct AI agents on what to do.
 
-Provider paths and argument placeholders are listed in [docs/integrations.md](docs/integrations.md).
+## Supported AI Tools
 
-## Quickstart
+| Category | Tools |
+| --- | --- |
+| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
+| CLI agents | Claude Code, Droid CLI, CodeBuddy CLI, OpenCode, Gemini CLI, Qwen Code, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI |
+| Universal adapters | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
 
-### For AI Agents (Recommended)
+Full list and configuration: [docs/integrations.md](docs/integrations.md)
 
-Most Clavix users work through AI coding assistants:
+## Quickstart
 
-> **💡 Choosing Your Mode:**
-> - **Fast/Deep** – Modifying or improving existing features
-> - **PRD** – Developing something completely new
->
-> See [Choosing the Right Mode](docs/guides/workflows.md#choosing-the-right-mode) for detailed guidance.
+### 1. Install and Initialize
 
 ```bash
-# 1. Initialize in your project
 npm install -g clavix
 clavix init
+```
+
+This creates `.clavix/` with slash command templates and injects documentation into your CLAUDE.md (or equivalent).
 
-# 2. Use slash commands in your AI agent
-/clavix:fast "Create a login page"
-/clavix:deep "Build an API for user management"
-/clavix:prd  # Full PRD workflow
+### 2. Use Slash Commands
 
-# 3. Manage saved prompts
-/clavix:execute  # Execute saved prompts
-/clavix:prompts  # Manage prompt lifecycle
+In your AI coding assistant (Claude Code, Cursor, etc.):
 
-# 4. Implement with task tracking
-clavix plan              # Generate tasks from PRD
-clavix implement         # Start implementation workflow
-clavix task-complete <taskId>  # Mark tasks done with auto-commit
 ```
+/clavix:improve "Create a secure login page with JWT"
+```
+
+The AI agent reads the improve template and:
+- Analyzes your prompt for quality
+- Applies optimization patterns
+- Saves the improved version to `.clavix/outputs/prompts/`
 
-**Supported agents**: Claude Code, Cursor, Windsurf, and [17+ more providers](docs/integrations.md)
+### 3. Choose Your Workflow
 
-Learn more: [Complete prompt lifecycle documentation](docs/commands/execute.md)
+| Command | When to Use |
+|---------|-------------|
+| `/clavix:improve` | Optimize a single prompt (auto-selects depth) |
+| `/clavix:prd` | Plan something new with guided questions |
+| `/clavix:start` | Explore ideas conversationally first |
+| `/clavix:plan` | Generate tasks from a PRD |
+| `/clavix:implement` | Execute tasks with progress tracking |
+| `/clavix:archive` | Archive completed projects |
 
-### Direct CLI Usage (Alternative)
+See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
 
-You can also use Clavix directly from the terminal:
+### 4. Keep Templates Updated
 
 ```bash
-clavix init
-clavix fast "Create a login page"
-clavix deep "Build an API for user management"
-clavix prd
+clavix update   # After npm update clavix
 ```
 
+## CLI Commands
+
+Clavix v5 has only 4 CLI commands (for setup, not workflows):
+
+| Command | Purpose |
+|---------|---------|
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Update templates after package update |
+| `clavix config` | Manage configuration |
+| `clavix version` | Show version |
+
+**All workflows** (`/clavix:improve`, `/clavix:prd`, etc.) are **slash commands** that AI agents execute by reading markdown templates.
+
 ## Full documentation
 - Overview & navigation: [docs/README.md](docs/README.md)
-- Command reference: [docs/commands/](docs/commands/README.md)
-- Providers: [docs/integrations.md](docs/integrations.md)
-- Clavix Intelligence: [docs/clavix-intelligence.md](docs/clavix-intelligence.md)
-- Guides: [docs/guides/](docs/guides/workflows.md)
+- Integrations: [docs/integrations.md](docs/integrations.md)
+- How it works: [docs/how-it-works.md](docs/how-it-works.md)
+- Philosophy: [docs/philosophy.md](docs/philosophy.md)
+- v4 Architecture (archived): [docs/archive/v4-architecture.md](docs/archive/v4-architecture.md)
 
 ## Requirements
 
 ### For End Users
-- **Node.js ≥ 16.0.0** (ESM support required)
+- **Node.js >= 18.0.0**
 - npm or yarn package manager
+- An AI coding assistant (Claude Code, Cursor, Windsurf, etc.)
 
 ### For Contributors
-- **Node.js ≥ 16.0.0**
+- **Node.js >= 18.0.0**
 - Run tests: `npm test`
 - Lint: `npm run lint`
 - Build: `npm run build`

package/dist/cli/commands/update.js

@@ -216,25 +216,24 @@ export default class Update extends Command {
 This project uses Clavix for prompt improvement and PRD generation.
 
 ### Available Commands
+- \`clavix improve [prompt]\` - Unified prompt optimization with auto-depth selection
+- \`clavix improve --comprehensive [prompt]\` - Force comprehensive analysis
+- \`clavix improve --standard [prompt]\` - Force standard optimization
+- \`clavix analyze [prompt]\` - JSON analysis output for programmatic use
 - \`clavix prd\` - Generate a comprehensive PRD through guided questions
-- \`clavix fast [prompt]\` - Quick prompt improvements with smart triage
-- \`clavix deep [prompt]\` - Comprehensive prompt analysis
 - \`clavix start\` - Start a conversational session for iterative development
 - \`clavix summarize\` - Extract requirements from conversation history
-- \`clavix list\` - List all sessions and outputs
-- \`clavix show [session-id]\` - Show detailed session information
+- \`clavix execute [--latest]\` - Execute saved prompts
+- \`clavix verify [--latest]\` - Verify implementation against checklist
 
 ### Quick Start
 \`\`\`bash
+# Prompt optimization (auto-selects depth)
+clavix improve "Build a user auth system"
+
 # Generate a PRD
 clavix prd
 
-# Quick prompt improvement
-clavix fast "Build a user auth system"
-
-# Deep prompt analysis
-clavix deep "Build a user auth system"
-
 # Start conversational mode
 clavix start
 \`\`\`

package/dist/templates/agents/agents.md

@@ -9,7 +9,7 @@ This guide is for agents that can only read documentation (no slash-command supp
 **CRITICAL: Know which mode you're in and STOP at the right point.**
 
 **OPTIMIZATION workflows** (NO CODE ALLOWED):
-- Fast/deep optimization - Prompt improvement only
+- Improve mode - Prompt optimization only (auto-selects depth)
 - Your role: Analyze, optimize, show improved prompt, **STOP**
 - ❌ DO NOT implement the prompt's requirements
 - ✅ After showing optimized prompt, tell user: "Run `/clavix:execute --latest` to implement"
@@ -38,11 +38,11 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 |----------|-----------------|---------|
 | **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
 | **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
-| **Quick Optimization** | `workflows/fast.md` | Intent detection + quality assessment + smart triage |
-| **Deep Analysis** | `workflows/deep.md` | Comprehensive with alternatives, validation, edge cases |
+| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
 | **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
 | **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
 | **File Operations** | `core/file-operations.md` | File creation patterns |
+| **Verification** | `core/verification.md` | Post-implementation verification |
 
 **Troubleshooting:**
 - `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
@@ -55,11 +55,12 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 
 | Keywords in User Request | Recommended Workflow | File Reference |
 |---------------------------|---------------------|----------------|
-| "improve this prompt", "make it better", "optimize" | Fast mode → Quick optimization | `workflows/fast.md` |
-| "analyze thoroughly", "edge cases", "alternatives" | Deep mode → Comprehensive analysis | `workflows/deep.md` |
+| "improve this prompt", "make it better", "optimize" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
+| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.md` |
 | "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` |
+| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
 
 **When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
 
@@ -70,11 +71,14 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 | Command | Purpose |
 |---------|---------|
 | `clavix init` | Interactive setup with integration selection |
-| `clavix fast "<prompt>"` | Quick optimization (CLI auto-saves; agent must save manually per template instructions) |
-| `clavix deep "<prompt>"` | Deep analysis (CLI auto-saves; agent must save manually per template instructions) |
+| `clavix improve "<prompt>"` | Unified optimization with auto-depth selection |
+| `clavix improve --comprehensive "<prompt>"` | Force comprehensive analysis |
+| `clavix improve --standard "<prompt>"` | Force standard optimization |
+| `clavix analyze "<prompt>"` | JSON analysis output for programmatic use |
 | `clavix execute [--latest]` | Execute saved prompts (interactive or --latest) |
+| `clavix verify [--latest]` | Verify implementation against checklist |
 | `clavix prompts list` | View saved prompts with status (NEW, EXECUTED, OLD, STALE) |
-| `clavix prompts clear` | Manage cleanup (--executed, --stale, --fast, --deep, --all, --force) |
+| `clavix prompts clear` | Manage cleanup (--executed, --stale, --standard, --comprehensive, --all) |
 | `clavix prd` | Guided PRD generation → `full-prd.md` + `quick-prd.md` |
 | `clavix plan` | Transform PRD → phase-based `tasks.md` |
 | `clavix implement [--commit-strategy=<type>]` | Execute tasks (git strategies: per-task, per-5-tasks, per-phase, none) |
@@ -91,6 +95,8 @@ clavix init
 clavix version
 ```
 
+**Save behavior:** CLI auto-saves prompts to `.clavix/outputs/`. When using slash commands, the agent must save manually per template instructions (no automatic persistence).
+
 ---
 
 ## 🔄 Standard Workflow

package/dist/templates/agents/copilot-instructions.md

@@ -1,6 +1,6 @@
 # Clavix Instructions for GitHub Copilot
 
-These instructions enhance GitHub Copilot's understanding of Clavix Intelligence™ workflows available in this project.
+These instructions enhance GitHub Copilot's understanding of Clavix prompt optimization workflows available in this project.
 
 ---
 

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

@@ -57,7 +57,7 @@ Checkpoints are standardized markers that agents output to confirm workflow step
 
 **After multi-step processes:**
 ```markdown
-**CHECKPOINT:** Completed Clavix Intelligence™ optimization - 5 improvements applied
+**CHECKPOINT:** Completed pattern-based optimization - 5 improvements applied
 **CHECKPOINT:** Analyzed conversation - extracted 12 requirements, 3 constraints
 ```
 
@@ -273,7 +273,7 @@ If workflow isn't proceeding as expected, check:
    **CHECKPOINT:** All files verified - exist at expected paths
 
 6. After optimization:
-   **CHECKPOINT:** Applied Clavix Intelligence™ - [N] improvements added
+   **CHECKPOINT:** Applied optimization patterns - [N] improvements added
 
 7. Workflow complete:
    **CHECKPOINT:** Summarization workflow complete - all outputs created