clavix 2.0.0 → 2.1.2

package/README.md

@@ -1,620 +1,59 @@
 # Clavix
+> AI prompt improvement & PRD generation CLI (CLEAR Framework)
 
-> AI prompt improvement and PRD generation CLI tool for developers
->
-> **Built on the CLEAR Framework** - Academically-validated prompt engineering methodology
-
-Clavix helps developers create better prompts and structured Product Requirements Documents (PRDs) for AI-assisted development tools like Claude Code. Using the CLEAR Framework (Concise, Logical, Explicit, Adaptive, Reflective) and Socratic questioning, Clavix ensures your requirements are clear, complete, and actionable.
-
-## Installation
-
-```bash
-npm install -g clavix
-```
-
-Or run without global install (no global state):
-
-```bash
-npx clavix@latest --help
-npx clavix@latest init
-```
-
-**Troubleshooting:**
-- If you encounter permission errors, use `sudo npm install -g clavix` (macOS/Linux)
-- On Windows, run your terminal as Administrator
-- Verify installation with `clavix version`
-
-## Supported Providers
-
-Clavix integrates seamlessly with multiple AI development tools:
-
-### IDE & IDE Extensions
-| Tool | Slash Commands | Directory | Status |
-|------|----------------|-----------|--------|
-| **Claude Code** | ✅ | `.claude/commands/clavix/` | Fully Supported |
-| **Cursor** | ✅ | `.cursor/commands/` | Fully Supported |
-| **Windsurf** | ✅ | `.windsurf/workflows/` | Fully Supported |
-| **Kilocode** | ✅ | `.kilocode/workflows/` (flat, no subdirectories) | Fully Supported |
-| **Roocode** | ✅ | `.roo/commands/` | Fully Supported |
-| **Cline** | ✅ | `.cline/workflows/` (flat, no subdirectories) | Fully Supported |
-
-### CLI Tools
-| Tool | Slash Commands | Directory | Status |
-|------|----------------|-----------|--------|
-| **Droid CLI** | ✅ | `.factory/commands/` (YAML frontmatter) | Fully Supported |
-| **CodeBuddy CLI** | ✅ | `.codebuddy/commands/` (YAML frontmatter, shell-style args) | Fully Supported |
-| **OpenCode** | ✅ | `.opencode/command/` | Fully Supported |
-| **Gemini CLI** | ✅ | `.gemini/commands/` (TOML custom commands) | Fully Supported |
-| **Qwen Code CLI** | ✅ | `.qwen/commands/` (TOML custom commands) | Fully Supported |
-| **Amp** | ✅ | `.agents/commands/` (no frontmatter) | Fully Supported |
-| **Crush CLI** | ✅ | `.crush/commands/clavix/` | Fully Supported |
-| **Codex CLI** | ✅ | `~/.codex/prompts` (global YAML frontmatter) | Fully Supported |
-
-### Universal Adapters
-| Tool | Slash Commands | Directory | Status |
-|------|----------------|-----------|--------|
-| **Universal (agents.md)** | ⚡ No slash commands | `AGENTS.md` | Fully Supported |
-| **Octofriend** | ⚡ No slash commands | `OCTO.md` | Fully Supported |
-
-**Key Features:**
-- **Multi-Select Support** - Choose multiple tools during `clavix init`
-- **Provider-Specific Formatting** - Commands generated in each tool's native format (e.g., Crush CLI uses `$PROMPT`, Droid & CodeBuddy add YAML `description`/`argument-hint`, Gemini/Qwen emit TOML with `{{args}}`, Codex expands `$ARGUMENTS`, Amp omits frontmatter)
-- **Universal Fallback** - `agents.md` works with any tool
-- **Managed Documentation** - Auto-inject and update instructions
-
-#### Argument placeholder reference
-
-| Provider | Placeholder |
-|----------|-------------|
-| Droid CLI | `$ARGUMENTS`
-| CodeBuddy CLI | `$1` (additional args: `$2`, `$3`, ...)
-| OpenCode | `$ARGUMENTS`
-| Gemini CLI | `{{args}}`
-| Qwen Code CLI | `{{args}}`
-| Amp | *(no inline placeholder; raw prompt)*
-| Crush CLI | `$PROMPT`
-| Codex CLI | `$ARGUMENTS`
+## Table of contents
+- [Why Clavix?](#why-clavix)
+- [Why CLEAR?](#why-clear)
+- [Providers](#providers)
+- [Quickstart](#quickstart)
+- [Full documentation](#full-documentation)
 
 ## Why Clavix?
-
-AI-assisted development tools produce better code when given better prompts. However, developers often struggle to write comprehensive, structured prompts that clearly communicate requirements, constraints, and success criteria. Clavix solves this by:
-
-- **Analyzing prompts** to identify gaps, ambiguities, and missing details
-- **Generating structured PRDs** through guided Socratic questioning
-- **Integrating seamlessly** with your AI development workflow
-- **Working offline** - no API calls, fully local operation
+Better prompts lead to better code. Clavix analyzes gaps, generates PRDs, and integrates with your AI tooling so you can move from idea to implementation quickly. Learn more in [docs/why-clavix.md](docs/why-clavix.md).
 
 ## Why CLEAR?
+Clavix is built on CLEAR (Concise, Logical, Explicit, Adaptive, Reflective), an academically validated prompt engineering methodology. Read the full overview in [docs/clear-framework.md](docs/clear-framework.md).
 
-**CLEAR Framework** is an academically-validated methodology for prompt engineering developed by **Dr. Leo Lo**, Dean of Libraries at the University of New Mexico, and published in the *Journal of Academic Librarianship* (July 2023).
-
-**The five CLEAR components:**
-- **[C] Concise** - Eliminate verbosity, remove pleasantries, focus on essentials
-- **[L] Logical** - Ensure coherent sequencing (context → requirements → constraints → output)
-- **[E] Explicit** - Specify persona, output format, tone, and success criteria
-- **[A] Adaptive** - Provide alternative approaches, flexibility, and customization
-- **[R] Reflective** - Enable validation, edge case analysis, and quality checks
-
-**Benefits:** Research-backed methodology, proven effectiveness, modern approach to AI interaction, educational feedback on prompt improvements.
-
-**Academic Citation:**
-Lo, L. S. (2023). "The CLEAR Path: A Framework for Enhancing Information Literacy through Prompt Engineering." *Journal of Academic Librarianship*, 49(4). [Framework Guide](https://guides.library.tamucc.edu/prompt-engineering/clear)
-
-## Features
-
-### 🎯 CLEAR Framework Prompt Engineering
-
-- **Fast Mode** - CLEAR-guided quick improvements (C, L, E components) with smart triage
-- **Deep Mode** - Full CLEAR framework analysis (C, L, E, A, R) with comprehensive validation
-- **CLEAR Assessment** - Score each component (0-100), overall rating, educational feedback with labeled improvements
-
-### 📋 CLEAR-Validated PRD Generation
-
-- **Vibecoding-Optimized** - 5 focused questions instead of lengthy requirement gathering
-- **Smart Tech Detection** - Auto-detects stack from project files (package.json, requirements.txt, etc.)
-- **CLEAR Validation** - Generated PRDs are analyzed for AI consumption quality (C, L, E components)
-- **Dual Output Format** - Comprehensive team PRD (`full-prd.md`) + CLEAR-optimized AI-ready version (`quick-prd.md`)
-- **Handlebars Templates** - Fully customizable PRD formats with template override support
-
-### 🚀 PRD-to-Implementation Workflow
-
-- **Task Planning** - Auto-generate implementation task breakdown from PRD with CLEAR-optimized atomic tasks
-- **Session Resume** - Stateful task tracking via markdown checkboxes, resume from last incomplete task
-- **Git Auto-Commit** - Optional automatic commits (per-task, per-5-tasks, per-phase) with descriptive messages
-- **AI-Assisted Execution** - Seamless handoff from strategic planning (PRD) to tactical implementation
+## Providers
 
-### 💬 CLEAR-Optimized Conversational Mode
+| Category | Providers |
+| --- | --- |
+| IDE & editor extensions | Cursor · Windsurf · Kilocode · Roocode · Cline |
+| CLI agents | Claude Code · Droid CLI · CodeBuddy CLI · OpenCode · Gemini CLI · Qwen Code · Amp · Crush CLI · Codex CLI |
+| Universal adapters | AGENTS.md · OCTO.md · WARP.md |
 
-- **Session Management** - Track conversations with UUID-based sessions, metadata, tags, and status tracking
-- **Message History** - Complete conversation logs with user/assistant role tracking
-- **CLEAR Extraction** - Extract and optimize prompts using CLEAR framework, display both raw and CLEAR-enhanced versions
-- **Search & Filter** - Find sessions by project, agent, status, tags, keywords, or date range
-
-### 🤖 Multi-Provider AI Agent Integration
-
-Clavix works with all major AI development tools (see [Supported Providers](#supported-providers) above).
-
-**Available Slash Commands:**
-- `/clavix:fast` - Quick CLEAR improvements
-- `/clavix:deep` - Full CLEAR analysis
-- `/clavix:prd` - Generate PRD
-- `/clavix:plan` - Generate task breakdown
-- `/clavix:implement` - Execute tasks
-- `/clavix:archive` - Archive completed projects
-- `/clavix:start` - Start conversational mode
-- `/clavix:summarize` - Extract optimized prompts
-
-**Integration Features:**
-- Provider-specific command formatting (e.g., Crush CLI uses `$PROMPT`; Droid CLI adds YAML `description`/`argument-hint`; Amp omits frontmatter)
-- Interactive multi-select during `clavix init`
-- Automatic documentation injection with managed blocks
-- Extensible plugin-based architecture for adding new providers
-
-### ⚙️ Configuration & Management
-
-- **Project Configuration** - Customize templates, output paths, agent selection, and preferences via `.clavix/config.json`
-- **Interactive CLI** - View current config, change settings, edit preferences, or reset to defaults
-- **Template System** - Override built-in templates with custom versions in `.clavix/templates/`
-- **Atomic File Operations** - Safe writes and updates prevent data corruption
-
-### 📚 Documentation Management
-
-- **Managed Blocks** - Auto-inject instructions with `<!-- CLAVIX:START -->` `<!-- CLAVIX:END -->` markers
-- **Update Command** - Keep slash commands and documentation synchronized across updates
-- **Safe Updates** - Preserve manual content while refreshing managed sections
-- **Migration Support** - Automatic cleanup of old command structures
-
-### 🔧 CLI Commands
-
-- `clavix init` - Initialize Clavix in your project with multi-provider selection (checkbox UI)
-- `clavix fast <prompt>` - CLEAR-guided quick improvements (C, L, E components)
-  - `--clear-only` - Show only CLEAR scores without improved prompt
-  - `--framework-info` - Display CLEAR framework information
-- `clavix deep <prompt>` - Full CLEAR framework analysis (C, L, E, A, R)
-  - `--clear-only` - Show only CLEAR scores without improved prompt
-  - `--framework-info` - Display CLEAR framework information
-- `clavix prd` - Generate CLEAR-validated PRD through Socratic questions
-- `clavix plan` - Generate implementation task breakdown from PRD
-- `clavix implement` - Execute tasks from the implementation plan with AI assistance
-- `clavix archive` - Archive completed PRD projects (`--list`, `--restore <project>`)
-- `clavix start` - Begin conversational session for iterative development
-- `clavix summarize [session-id]` - Extract and CLEAR-optimize prompts from conversation
-- `clavix list` - List sessions and outputs with filtering options
-- `clavix show [session-id]` - View detailed session/output information
-- `clavix config` - Manage configuration (get/set/edit/reset)
-- `clavix update` - Update managed blocks and slash commands
-- `clavix version` - Display version information
-
-## Quick Start
-
-### 1. Initialize in Your Project
+Provider paths and argument placeholders are listed in [docs/providers.md](docs/providers.md).
 
+## Quickstart
 ```bash
-cd your-project
-clavix init
-```
-
-You'll be prompted to select which AI tools to support:
-```
-? Which AI tools are you using? (Space to select, Enter to confirm)
- ◉ Claude Code (.claude/commands/clavix/)
- ◉ Cursor (.cursor/commands/)
- ◯ Droid CLI (.factory/commands/)
- ◯ CodeBuddy CLI (.codebuddy/commands/)
- ◉ OpenCode (.opencode/command/)
- ◯ Gemini CLI (.gemini/commands/)
- ◯ Qwen Code CLI (.qwen/commands/)
- ◯ Amp (.agents/commands/)
- ◉ agents.md (Universal)
- ◯ Octofriend (OCTO.md - Universal)
- ◯ Codex CLI (~/.codex/prompts)
-```
-
-This will:
-- Create `.clavix/` directory with configuration
-- Generate slash commands for all selected providers
-- Create universal `AGENTS.md` for tools without slash commands
-- Inject managed blocks into documentation files
-
-### 2. Improve a Prompt with CLEAR Framework
-
-**Fast mode** (C, L, E components):
-```bash
-clavix fast "Create a login page"
-```
-
-**Deep mode** (full CLEAR - C, L, E, A, R):
-```bash
-clavix deep "Create a login page"
+npm install -g clavix
+# or without a global install
+npx clavix@latest init
 ```
 
-**Framework info:**
-```bash
-clavix fast --framework-info
-```
-
-Output:
-- **CLEAR Assessment** - Component scores (Conciseness, Logic, Explicitness + Adaptive & Reflective in deep mode)
-- **CLEAR-Optimized Prompt** - Improved version applying all CLEAR principles
-- **CLEAR Changes Made** - Educational feedback labeled with [C], [L], [E], [A], [R] components
-- **Smart Triage** - CLEAR-aware recommendations for when to use deep mode
-- **Adaptive Variations** - Alternative phrasings and structures (deep mode)
-- **Reflection Checklist** - Validation steps and edge cases (deep mode)
-
-### 3. Use Slash Commands (All Providers)
-
-After initialization, use these CLEAR-enhanced commands in your AI tool:
-
-- `/clavix:fast [prompt]` - CLEAR-guided quick improvements (C, L, E)
-- `/clavix:deep [prompt]` - Full CLEAR framework analysis (C, L, E, A, R)
-- `/clavix:prd` - Generate CLEAR-validated PRD
-- `/clavix:plan` - Generate task breakdown from PRD
-- `/clavix:implement` - Execute tasks with AI assistance
-- `/clavix:start` - Start conversational mode
-- `/clavix:summarize` - Extract and CLEAR-optimize from conversation
-
-## Commands
-
-### `clavix init`
-
-Initialize Clavix in the current project.
-
+Common commands:
 ```bash
 clavix init
-```
-
-Interactive prompts guide you through:
-- Agent selection (Claude Code, more coming soon)
-- Directory structure creation
-- Slash command generation
-- Documentation injection
-
-### `clavix fast <prompt>`
-
-Quick prompt improvements with smart triage.
-
-```bash
-clavix fast "Build an API for user management"
-```
-
-**Features:**
-- Fast analysis of gaps, ambiguities, strengths
-- Smart triage: recommends deep mode for complex prompts
-- "Already good" assessment for quality prompts
-- Changes made summary (educational)
-- Single structured improved prompt
-
-**Smart triage checks:**
-- Prompts < 20 characters
-- Missing 3+ critical elements
-- Vague scope words without context
-
-### `clavix deep <prompt>`
-
-Comprehensive prompt analysis.
-
-```bash
+clavix fast "Create a login page"
 clavix deep "Build an API for user management"
-```
-
-**Everything from fast mode PLUS:**
-- Alternative phrasings of requirements
-- Edge cases in requirements
-- Good/bad implementation examples
-- Multiple prompt structuring approaches
-- "What could go wrong" analysis
-- More thorough clarifying questions
-
-**Output:**
-- Structured prompt with sections:
-  - Objective
-  - Requirements
-  - Technical Constraints
-  - Expected Output
-  - Success Criteria
-  - Plus all deep mode analysis sections
-
-### `clavix prd`
-
-Generate a comprehensive PRD through 5 focused questions (optimized for vibecoding).
-
-```bash
 clavix prd
 ```
 
-Features:
-- **5 streamlined questions** - Fast workflow without losing quality
-- **Smart tech detection** - Auto-detects stack from package.json, requirements.txt, etc.
-- **CLEAR validated** - Automatic quality analysis for AI consumption
-
-Creates two files:
-- `full-prd.md` - Comprehensive document for team alignment
-- `quick-prd.md` - Condensed version for AI consumption
-
-### `clavix plan`
-
-Generate implementation task breakdown from PRD.
-
-```bash
-clavix plan
-```
-
-**Features:**
-- Analyzes PRD and generates `tasks.md` with CLEAR-optimized tasks
-- Organizes tasks into logical phases/sections
-- Creates markdown checkbox format for progress tracking
-- Each task is atomic and independently implementable
-- Tasks reference specific PRD sections for context
-
-**Options:**
-```bash
-clavix plan --project my-app           # Specify PRD project
-clavix plan --prd-path .clavix/outputs/my-project  # Direct path
-clavix plan --overwrite                 # Regenerate existing tasks.md
-```
-
-**Output format:**
-```markdown
-## Phase 1: Authentication
-- [ ] Implement user registration endpoint
-- [ ] Add password hashing with bcrypt
-- [ ] Create JWT token generation
-
-## Phase 2: Authorization
-- [ ] Implement role-based access control
-- [ ] Add middleware for protected routes
-```
-
-### `clavix implement`
-
-Execute tasks from the implementation plan with AI assistance.
-
-```bash
-clavix implement
-```
-
-**Workflow:**
-1. Reads `tasks.md` and finds first incomplete task
-2. Shows current progress (completed/total)
-3. Prompts for git auto-commit preferences
-4. Creates configuration for AI agent
-5. AI agent implements tasks sequentially
-6. Marks completed tasks: `[ ]` → `[x]`
-7. Creates commits based on strategy
-8. Resumes from last checkpoint in new sessions
-
-**Git Auto-Commit Strategies:**
-- **Per phase** - Commit when all tasks in a phase complete
-- **Per 5 tasks** - Commit after every 5 tasks
-- **Per task** - Commit after each individual task
-- **None** - Manual git management
-
-**Options:**
-```bash
-clavix implement --project my-app       # Specify PRD project
-clavix implement --no-git               # Skip git setup
-clavix implement --commit-strategy per-task  # Set commit strategy
-```
-
-**Example commit message:**
-```
-clavix: Implement user authentication
-
-Completed tasks:
-- Implement user registration endpoint
-- Add password hashing with bcrypt
-- Create JWT token generation
-
-Project: my-app
-Generated by Clavix /clavix:implement
-```
-
-### `clavix archive`
-
-Archive completed PRD projects to keep your workspace organized.
-
-```bash
-# Interactive mode - select projects to archive
-clavix archive
-
-# Archive specific project
-clavix archive my-project
-
-# List archived projects
-clavix archive --list
-
-# Restore archived project
-clavix archive --restore my-project
-
-# Force archive (skip incomplete task verification)
-clavix archive my-project --force
-```
+## Full documentation
+- Overview & navigation: [docs/index.md](docs/index.md)
+- Command reference: [docs/commands/](docs/commands/README.md)
+- Providers: [docs/providers.md](docs/providers.md)
+- CLEAR Framework: [docs/clear-framework.md](docs/clear-framework.md)
+- Guides: [docs/guides/](docs/guides/workflows.md)
 
-**How it works:**
-- Archives projects from `.clavix/outputs/` to `.clavix/outputs/archive/`
-- Validates all tasks are completed before archiving (unless `--force` used)
-- Preserves all PRD files, task files, and implementation plans
-- List view shows completion status, task counts, and archive dates
-- Supports multiple PRD naming conventions: `PRD.md`, `full-prd.md`, `FULL_PRD.md`, `QUICK_PRD.md`
-
-**Slash Command:**
-```
-/clavix:archive
-```
-Available in: Claude Code, Cursor, Droid, OpenCode, Amp, Crush, Windsurf, Kilocode, Cline, Roocode
-
-### `clavix start`
-
-Enter conversational mode for iterative requirement gathering.
-
-```bash
-clavix start
-```
-
-Start a natural conversation to develop requirements. Use `/clavix:summarize` later to extract structured output.
-
-### `clavix summarize [session-id]`
-
-Analyze a conversation and extract requirements.
-
-```bash
-# Summarize current session
-clavix summarize
-
-# Summarize specific session
-clavix summarize abc-123-def
-```
-
-Generates:
-- `mini-prd.md` - Concise requirements
-- `optimized-prompt.md` - AI-ready prompt
-
-### `clavix list`
-
-List all sessions and outputs.
-
-```bash
-# List everything
-clavix list
-
-# List only sessions
-clavix list --sessions
-
-# Filter by project
-clavix list --project auth
-```
-
-### `clavix show [session-id]`
-
-Show detailed session information.
-
-```bash
-# Show most recent session
-clavix show
-
-# Show specific session with full history
-clavix show abc-123-def --full
-
-# Show output directory
-clavix show --output project-name
-```
-
-### `clavix config`
-
-Manage configuration.
-
-```bash
-# Interactive menu
-clavix config
-
-# Get/set values
-clavix config get agent
-clavix config set preferences.verboseLogging true
-```
-
-### `clavix update`
-
-Update managed blocks and slash commands.
-
-```bash
-# Update everything
-clavix update
-
-# Update specific components
-clavix update --docs-only
-clavix update --commands-only
-```
-
-### `clavix version`
-
-Display the current version of Clavix.
-
-```bash
-clavix version
-```
-
-### `clavix --help`
-
-Display help information for all commands.
-
-```bash
-clavix --help
-clavix fast --help
-clavix deep --help
-```
-
-## Project Structure
-
-After initialization, your project will have:
-
-```
-your-project/
-├── .clavix/
-│   ├── config.json         # Clavix configuration
-│   ├── INSTRUCTIONS.md     # Usage guide
-│   ├── sessions/           # Conversational mode sessions
-│   ├── outputs/            # Generated PRDs and prompts
-│   │   └── project-name/
-│   │       ├── PRD.md      # Full PRD
-│   │       ├── PRD-quick.md  # Quick PRD
-│   │       ├── tasks.md    # Implementation tasks
-│   │       └── .clavix-implement-config.json  # Implementation config
-│   └── templates/          # Custom templates (optional)
-├── AGENTS.md               # Updated with Clavix block
-├── CLAUDE.md               # Updated with Clavix block (if Claude Code)
-└── .claude/commands/       # Generated slash commands (if Claude Code)
-    ├── clavix/
-    │   ├── fast.md
-    │   ├── deep.md
-    │   ├── prd.md
-    │   ├── plan.md
-    │   ├── implement.md
-    │   ├── start.md
-    │   └── summarize.md
-```
-
-## Configuration
-
-Clavix stores configuration in `.clavix/config.json`:
-
-```json5
-{
-  version: "1.0.0",
-  agent: "claude-code",
-  templates: {
-    prdQuestions: "default",
-    fullPrd: "default",
-    quickPrd: "default"
-  },
-  outputs: {
-    path: ".clavix/outputs",
-    format: "markdown"
-  },
-  preferences: {
-    autoOpenOutputs: false,
-    verboseLogging: false,
-    preserveSessions: true
-  }
-}
-```
-
-## Customization
-
-### Custom Templates
-
-Override default templates by adding files to `.clavix/templates/`:
-
-- `prd-questions.md` - Custom PRD questions
-- `full-prd-template.hbs` - Full PRD format
-- `quick-prd-template.hbs` - Quick PRD format
-
-Templates use Handlebars syntax.
-
-## Examples
-
-### Example 1: Minimal to Comprehensive
+## Development
+- Requires Node.js ≥ 18
+- Run tests: `npm test`
+- Lint: `npm run lint`
+- Build: `npm run build`
 
-**Original:**
+## License
+MIT
 ```
 Create a login page
 ```

package/dist/cli/commands/implement.js

@@ -227,7 +227,7 @@ class Implement extends core_1.Command {
             }
             // Check if tasks.md exists
             const hasTasks = await fs.pathExists(tasksPath);
-            let stats = null;
+            let stats;
             if (hasTasks) {
                 try {
                     const phases = await manager.readTasksFile(tasksPath);

package/dist/cli/commands/init.js

@@ -45,6 +45,7 @@ const agent_manager_1 = require("../../core/agent-manager");
 const doc_injector_1 = require("../../core/doc-injector");
 const agents_md_generator_1 = require("../../core/adapters/agents-md-generator");
 const octo_md_generator_1 = require("../../core/adapters/octo-md-generator");
+const warp_md_generator_1 = require("../../core/adapters/warp-md-generator");
 const file_system_1 = require("../../utils/file-system");
 const config_1 = require("../../types/config");
 const gemini_adapter_1 = require("../../core/adapters/gemini-adapter");
@@ -80,32 +81,6 @@ class Init extends core_1.Command {
                     name: 'selectedProviders',
                     message: 'Which AI tools are you using?',
                     choices: [
-                        // IDE & IDE Extensions
-                        {
-                            name: 'Claude Code (.claude/commands/clavix/)',
-                            value: 'claude-code',
-                        },
-                        {
-                            name: 'Cline (.clinerules/workflows/)',
-                            value: 'cline',
-                        },
-                        {
-                            name: 'Cursor (.cursor/commands/)',
-                            value: 'cursor',
-                        },
-                        {
-                            name: 'Kilocode (.kilocode/workflows/)',
-                            value: 'kilocode',
-                        },
-                        {
-                            name: 'Roocode (.roo/commands/)',
-                            value: 'roocode',
-                        },
-                        {
-                            name: 'Windsurf (.windsurf/workflows/)',
-                            value: 'windsurf',
-                        },
-                        new inquirer_1.default.Separator(),
                         // CLI Tools
                         {
                             name: 'Amp (.agents/commands/)',
@@ -131,6 +106,10 @@ class Init extends core_1.Command {
                             name: 'Crush CLI (.crush/commands/clavix/)',
                             value: 'crush',
                         },
+                        {
+                            name: 'Claude Code (.claude/commands/clavix/)',
+                            value: 'claude-code',
+                        },
                         {
                             name: 'Droid CLI (.factory/commands/)',
                             value: 'droid',
@@ -148,11 +127,37 @@ class Init extends core_1.Command {
                             value: 'qwen',
                         },
                         new inquirer_1.default.Separator(),
+                        // IDE & IDE Extensions
+                        {
+                            name: 'Cursor (.cursor/commands/)',
+                            value: 'cursor',
+                        },
+                        {
+                            name: 'Windsurf (.windsurf/workflows/)',
+                            value: 'windsurf',
+                        },
+                        {
+                            name: 'Kilocode (.kilocode/workflows/)',
+                            value: 'kilocode',
+                        },
+                        {
+                            name: 'Roocode (.roo/commands/)',
+                            value: 'roocode',
+                        },
+                        {
+                            name: 'Cline (.clinerules/workflows/)',
+                            value: 'cline',
+                        },
+                        new inquirer_1.default.Separator(),
                         // Universal Adapters
                         {
                             name: 'agents.md (Universal - for tools without slash commands)',
                             value: 'agents-md',
                         },
+                        {
+                            name: 'Warp (WARP.md - optimized for Warp)',
+                            value: 'warp-md',
+                        },
                         {
                             name: 'Octofriend (OCTO.md - optimized for Octofriend)',
                             value: 'octo-md',
@@ -194,6 +199,11 @@ class Init extends core_1.Command {
                     await octo_md_generator_1.OctoMdGenerator.generate();
                     continue;
                 }
+                if (providerName === 'warp-md') {
+                    console.log(chalk_1.default.gray('  ✓ Generating WARP.md...'));
+                    await warp_md_generator_1.WarpMdGenerator.generate();
+                    continue;
+                }
                 let adapter = agentManager.requireAdapter(providerName);
                 console.log(chalk_1.default.gray(`  ✓ Generating ${adapter.displayName} commands...`));
                 if (adapter.name === 'codex') {

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

@@ -16,5 +16,6 @@ export default class Update extends Command {
     private hasUpToDateBlock;
     private updateAgentsMd;
     private updateOctoMd;
+    private updateWarpMd;
 }
 //# sourceMappingURL=update.d.ts.map

package/dist/cli/commands/update.js

@@ -46,6 +46,7 @@ const doc_injector_1 = require("../../core/doc-injector");
 const agent_manager_1 = require("../../core/agent-manager");
 const agents_md_generator_1 = require("../../core/adapters/agents-md-generator");
 const octo_md_generator_1 = require("../../core/adapters/octo-md-generator");
+const warp_md_generator_1 = require("../../core/adapters/warp-md-generator");
 const legacy_command_cleanup_1 = require("../../utils/legacy-command-cleanup");
 class Update extends core_1.Command {
     async run() {
@@ -69,23 +70,24 @@ class Update extends core_1.Command {
         let updatedCount = 0;
         // Update for each provider
         for (const providerName of providers) {
-            // Handle agents-md separately (not an adapter)
+            // Handle AGENTS.md separately
             if (providerName === 'agents-md') {
                 if (updateDocs) {
-                    const agentsPath = path.join(process.cwd(), 'AGENTS.md');
-                    if (fs.existsSync(agentsPath)) {
-                        updatedCount += await this.updateAgentsMd(flags.force);
-                    }
+                    updatedCount += await this.updateAgentsMd(flags.force);
                 }
                 continue;
             }
-            // Handle octo-md separately (not an adapter)
+            // Handle Warp separately
+            if (providerName === 'warp-md') {
+                if (updateDocs) {
+                    updatedCount += await this.updateWarpMd(flags.force);
+                }
+                continue;
+            }
+            // Handle Octofriend separately
             if (providerName === 'octo-md') {
                 if (updateDocs) {
-                    const octoPath = path.join(process.cwd(), 'OCTO.md');
-                    if (fs.existsSync(octoPath)) {
-                        updatedCount += await this.updateOctoMd(flags.force);
-                    }
+                    updatedCount += await this.updateOctoMd(flags.force);
                 }
                 continue;
             }
@@ -328,6 +330,19 @@ Analyze the current conversation and extract key requirements into a structured
             return 0;
         }
     }
+    async updateWarpMd(_force) {
+        this.log(chalk_1.default.cyan('📝 Updating WARP.md...'));
+        try {
+            await warp_md_generator_1.WarpMdGenerator.generate();
+            this.log(chalk_1.default.gray('  ✓ Updated WARP.md'));
+            return 1;
+        }
+        catch (error) {
+            const { getErrorMessage } = await Promise.resolve().then(() => __importStar(require('../../utils/error-utils.js')));
+            this.log(chalk_1.default.yellow(`  ⚠ Failed to update WARP.md: ${getErrorMessage(error)}`));
+            return 0;
+        }
+    }
 }
 Update.description = 'Update managed blocks and slash commands';
 Update.examples = [
@@ -337,7 +352,7 @@ Update.examples = [
 ];
 Update.flags = {
     'docs-only': core_1.Flags.boolean({
-        description: 'Update only documentation blocks (AGENTS.md, CLAUDE.md)',
+        description: 'Update only documentation blocks (AGENTS.md, CLAUDE.md, OCTO.md, WARP.md)',
         default: false,
     }),
     'commands-only': core_1.Flags.boolean({

package/dist/core/adapters/warp-md-generator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generator for Warp WARP.md file
+ * Provides workflow instructions optimized for Warp users
+ */
+export declare class WarpMdGenerator {
+    static readonly TARGET_FILE = "WARP.md";
+    static readonly START_MARKER = "<!-- CLAVIX:START -->";
+    static readonly END_MARKER = "<!-- CLAVIX:END -->";
+    /**
+     * Generate or update WARP.md with Clavix workflows
+     */
+    static generate(): Promise<void>;
+    private static injectManagedBlock;
+    private static escapeRegex;
+    static hasClavixBlock(): Promise<boolean>;
+}
+//# sourceMappingURL=warp-md-generator.d.ts.map

package/dist/core/adapters/warp-md-generator.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WarpMdGenerator = void 0;
+const file_system_1 = require("../../utils/file-system");
+const path = __importStar(require("path"));
+/**
+ * Generator for Warp WARP.md file
+ * Provides workflow instructions optimized for Warp users
+ */
+class WarpMdGenerator {
+    /**
+     * Generate or update WARP.md with Clavix workflows
+     */
+    static async generate() {
+        const templatePath = path.join(__dirname, '../../templates/agents/warp.md');
+        if (!(await file_system_1.FileSystem.exists(templatePath))) {
+            throw new Error(`WARP.md template not found at ${templatePath}`);
+        }
+        const template = await file_system_1.FileSystem.readFile(templatePath);
+        await this.injectManagedBlock(this.TARGET_FILE, template);
+    }
+    static async injectManagedBlock(filePath, content) {
+        let fileContent = '';
+        if (await file_system_1.FileSystem.exists(filePath)) {
+            fileContent = await file_system_1.FileSystem.readFile(filePath);
+        }
+        const blockRegex = new RegExp(`${this.escapeRegex(this.START_MARKER)}[\\s\\S]*?${this.escapeRegex(this.END_MARKER)}`, 'g');
+        const wrappedContent = `${this.START_MARKER}\n${content}\n${this.END_MARKER}`;
+        if (blockRegex.test(fileContent)) {
+            fileContent = fileContent.replace(blockRegex, wrappedContent);
+        }
+        else {
+            if (fileContent && !fileContent.endsWith('\n\n')) {
+                fileContent += '\n\n';
+            }
+            fileContent += wrappedContent + '\n';
+        }
+        await file_system_1.FileSystem.writeFileAtomic(filePath, fileContent);
+    }
+    static escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    static async hasClavixBlock() {
+        if (!(await file_system_1.FileSystem.exists(this.TARGET_FILE))) {
+            return false;
+        }
+        const content = await file_system_1.FileSystem.readFile(this.TARGET_FILE);
+        return content.includes(this.START_MARKER);
+    }
+}
+exports.WarpMdGenerator = WarpMdGenerator;
+WarpMdGenerator.TARGET_FILE = 'WARP.md';
+WarpMdGenerator.START_MARKER = '<!-- CLAVIX:START -->';
+WarpMdGenerator.END_MARKER = '<!-- CLAVIX:END -->';
+//# sourceMappingURL=warp-md-generator.js.map

package/dist/core/task-manager.js

@@ -127,13 +127,6 @@ class TaskManager {
         if (phases.length === 0 && sections.requirements) {
             phases.push(...this.generateTasksFromRequirements(sections.requirements, sections));
         }
-        // Ensure all tasks follow CLEAR principles
-        phases.forEach((phase) => {
-            phase.tasks = phase.tasks.map((task) => ({
-                ...task,
-                description: this.optimizeTaskDescription(task.description),
-            }));
-        });
         const technicalSection = this.getSectionByAliases(sections, [
             'technicalrequirements',
             'technicalconstraints',
@@ -151,6 +144,13 @@ class TaskManager {
         if (phases.length === 0) {
             phases.push(this.generateDefaultPhases(prdContent));
         }
+        // Ensure all tasks follow CLEAR principles (applied AFTER all tasks are added)
+        phases.forEach((phase) => {
+            phase.tasks = phase.tasks.map((task) => ({
+                ...task,
+                description: this.optimizeTaskDescription(task.description),
+            }));
+        });
         return phases;
     }
     getSectionByAliases(sections, aliases) {
@@ -454,15 +454,15 @@ class TaskManager {
      * Optimize task description using CLEAR principles
      */
     optimizeTaskDescription(description) {
-        // Ensure conciseness: limit to reasonable length
-        if (description.length > 150) {
-            description = description.substring(0, 147) + '...';
-        }
-        // Ensure starts with action verb
+        // Ensure starts with action verb first
         const actionVerbs = /^(Create|Add|Implement|Build|Generate|Read|Write|Parse|Analyze|Display|Update|Handle|Process|Execute|Mark|Track|Ensure|Validate|Configure|Set up|Fix|Refactor|Test)/i;
         if (!actionVerbs.test(description)) {
             description = `Implement ${description}`;
         }
+        // Ensure conciseness: limit to reasonable length (after adding action verb)
+        if (description.length > 150) {
+            description = description.substring(0, 147) + '...';
+        }
         return description;
     }
     /**

package/dist/templates/agents/agents.md

@@ -1,12 +1,39 @@
-# Clavix Workflows
+# Clavix Workflows (Universal)
 
-Quick workflow instructions for AI tools.
+Use these instructions when your agent can only read documentation (no slash-command support).
 
-## Fast Mode
-Use for quick prompt improvements.
+## Quick start
+- Install globally: `npm install -g clavix`
+- Or run ad hoc: `npx clavix@latest init`
+- Verify installation: `clavix version`
 
-## Deep Mode
-Use for comprehensive analysis.
+## Command reference
 
-## PRD Mode
-Use for strategic planning.
+| Command | Purpose |
+| --- | --- |
+| `clavix init` | Interactive setup. Select providers and generate documentation/command files. |
+| `clavix fast "<prompt>"` | CLEAR (C/L/E) analysis with improved prompt output. |
+| `clavix deep "<prompt>"` | Full CLEAR (C/L/E/A/R) analysis, alternative variations, validation checklists. |
+| `clavix prd` | Guided Socratic questions that generate `full-prd.md` and `quick-prd.md`. |
+| `clavix plan` | Transform PRDs or sessions into phase-based `tasks.md`. |
+| `clavix implement` | Walk through tasks, track progress, optionally set git auto-commit strategy. |
+| `clavix start` | Begin conversational capture session for requirements gathering. |
+| `clavix summarize [session-id]` | Extract mini PRD and optimized prompts from saved sessions. |
+| `clavix list` | List sessions and/or output projects (`--sessions`, `--outputs`, filters). |
+| `clavix show [session-id]` | Inspect session details or use `--output <project>` to view outputs. |
+| `clavix archive [project]` | Archive completed projects or restore them (`--restore`). |
+| `clavix config [get|set|edit|reset]` | Manage `.clavix/config.json` preferences. |
+| `clavix update` | Refresh managed docs and slash commands (supports `--docs-only`, `--commands-only`). |
+| `clavix version` | Print installed version. |
+
+## Typical workflows
+- **Improve prompts quickly:** run `clavix fast` or `clavix deep` depending on complexity.
+- **Create strategy:** run `clavix prd` then `clavix plan` for an implementation checklist.
+- **Execute tasks:** use `clavix implement`, commit work, repeat until tasks complete.
+- **Capture conversations:** record with `clavix start`, extract with `clavix summarize`.
+- **Stay organized:** inspect with `clavix list/show`, archive with `clavix archive`, refresh docs via `clavix update`.
+
+Artifacts are stored under `.clavix/`:
+- `.clavix/outputs/<project>/` for PRDs, tasks, prompts
+- `.clavix/sessions/` for captured conversations
+- `.clavix/templates/` for custom overrides

package/dist/templates/agents/octo.md

@@ -215,6 +215,25 @@ Detect user intent from keywords and trigger appropriate workflow. Use Octofrien
 
 ---
 
+### CLI reference cheat sheet
+
+| Command | Use it for |
+| --- | --- |
+| `clavix init` | Rebuild `.clavix` structure and regenerate provider assets. |
+| `clavix fast` / `clavix deep` | CLEAR-based prompt improvement (quick vs. comprehensive). |
+| `clavix prd` | Guided questions to create PRDs. |
+| `clavix plan` | Convert PRD artifacts into task lists. |
+| `clavix implement` | Step through tasks with optional git automation. |
+| `clavix start` | Capture conversational requirements. |
+| `clavix summarize` | Extract mini PRDs and prompts from sessions. |
+| `clavix list` | List sessions or outputs (use `--sessions`, `--outputs`, `--archived`). |
+| `clavix show` | Inspect sessions or output directories. |
+| `clavix archive` | Archive or restore project outputs. |
+| `clavix config` | View/update `.clavix/config.json`. |
+| `clavix update` | Refresh documentation and slash commands. |
+| `clavix version` | Display installed CLI version. |
+
+
 ## 📝 Workflow Selection Guide
 
 **User mentions PRD, requirements doc, strategic planning:**

package/dist/templates/agents/warp.md

@@ -0,0 +1,31 @@
+## Clavix Integration for Warp
+
+Clavix helps Warp developers turn rough ideas into CLEAR, AI-ready prompts and Product Requirements Documents without leaving the terminal.
+
+### Quick start
+- Install globally: `npm install -g clavix`
+- Or run ad hoc: `npx clavix@latest init`
+- Verify setup: `clavix version`
+
+### Common commands
+- `clavix init` – interactive provider setup (regenerates docs & commands)
+- `clavix fast "<prompt>"` – quick CLEAR (C/L/E) analysis and improved prompt
+- `clavix deep "<prompt>"` – full CLEAR (C/L/E/A/R) analysis with alternatives & checklists
+- `clavix prd` – answer focused questions to create full/quick PRDs
+- `clavix plan` – transform PRDs or sessions into task lists
+- `clavix implement` – progress through tasks with optional git auto-commit
+- `clavix start` – capture requirement conversations in Warp
+- `clavix summarize [session-id]` – extract mini PRDs and optimized prompts
+- `clavix list` – list sessions/outputs (`--sessions`, `--outputs`, `--archived`)
+- `clavix show [session-id]` – inspect sessions or use `--output <project>`
+- `clavix archive [project]` – archive projects (or `--restore` to bring them back)
+- `clavix config get|set|edit|reset` – manage `.clavix/config.json`
+- `clavix update` – refresh documentation/commands (`--docs-only`, `--commands-only`)
+- `clavix version` – print installed CLI version
+
+### Outputs
+- Project artifacts live under `.clavix/outputs/<project>/`
+- Sessions are stored in `.clavix/sessions/`
+- Update generated docs/commands any time with `clavix update`
+
+For full documentation, open `docs/index.md` in your project or visit the repository README.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "description": "AI prompt improvement and PRD generation CLI tool for developers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",