clavix 1.1.2 → 1.3.0

package/README.md

@@ -1,8 +1,10 @@
 # Clavix
 
 > 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. Through Socratic questioning and rule-based analysis, Clavix ensures your requirements are clear, complete, and actionable.
+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.
 
 ## Why Clavix?
 
@@ -13,23 +15,90 @@ AI-assisted development tools produce better code when given better prompts. How
 - **Integrating seamlessly** with your AI development workflow
 - **Working offline** - no API calls, fully local operation
 
+## Why CLEAR?
+
+**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
 
-### Phase 1 (MVP) ✅ Complete
+### 🎯 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
+
+- **Interactive Workflow** - Guided Socratic questioning with sequential and conditional flows
+- **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
+
+### 💬 CLEAR-Optimized Conversational Mode
+
+- **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
 
-- ✅ **Global CLI tool** - Install once, use everywhere
-- ✅ **Prompt improvement** - Analyze and enhance prompts directly
-- ✅ **Claude Code integration** - Slash commands in your AI agent
-- ✅ **Managed documentation** - Auto-inject into AGENTS.md and CLAUDE.md
-- ✅ **Template system** - Customizable templates for your workflow
+### 🤖 AI Agent Integration
 
-### Phase 2 (Core Workflows) ✅ Complete
+- **Claude Code Support** - Slash commands (`/clavix:fast`, `/clavix:deep`, `/clavix:prd`, `/clavix:plan`, `/clavix:implement`, `/clavix:start`, `/clavix:summarize`) with auto-detection
+- **Managed Documentation** - Auto-inject and update instructions in `AGENTS.md` and `CLAUDE.md` with safe managed blocks
+- **Extensible Architecture** - Adapter pattern ready for future Cursor, Windsurf, and other agent integrations
 
-- ✅ **PRD generation** - Guided Socratic questioning workflow
-- ✅ **Conversational mode** - Iterative prompt development
-- ✅ **Session management** - Track and organize conversations
-- ✅ **Analysis tools** - Extract optimized prompts from conversations
-- ✅ **Additional commands** - list, show, config, update
+### ⚙️ 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 agent selection
+- `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 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
 
 ## Installation
 
@@ -37,6 +106,11 @@ AI-assisted development tools produce better code when given better prompts. How
 npm install -g clavix
 ```
 
+**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`
+
 ## Quick Start
 
 ### 1. Initialize in Your Project
@@ -51,34 +125,42 @@ This will:
 - Generate slash commands for your AI agent
 - Inject managed blocks into AGENTS.md and CLAUDE.md
 
-### 2. Improve a Prompt
+### 2. Improve a Prompt with CLEAR Framework
 
-**Fast mode** (quick improvements):
+**Fast mode** (C, L, E components):
 ```bash
 clavix fast "Create a login page"
 ```
 
-**Deep mode** (comprehensive analysis):
+**Deep mode** (full CLEAR - C, L, E, A, R):
 ```bash
 clavix deep "Create a login page"
 ```
 
+**Framework info:**
+```bash
+clavix fast --framework-info
+```
+
 Output:
-- Analysis of gaps and ambiguities
-- Structured prompt with clear sections
-- Changes made summary
-- Smart triage recommendations (fast mode)
-- Alternative phrasings, edge cases, examples (deep mode)
+- **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 (Claude Code)
 
-After initialization, use these commands in Claude Code:
+After initialization, use these CLEAR-enhanced commands in Claude Code:
 
-- `/clavix:fast [prompt]` - Quick prompt improvements
-- `/clavix:deep [prompt]` - Comprehensive prompt analysis
-- `/clavix:prd` - Generate a PRD
+- `/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` - Analyze conversation
+- `/clavix:summarize` - Extract and CLEAR-optimize from conversation
 
 ## Commands
 
@@ -153,6 +235,84 @@ 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 start`
 
 Enter conversational mode for iterative requirement gathering.
@@ -264,15 +424,23 @@ your-project/
 │   ├── 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
-    ├── clavix:deep.md
-    ├── clavix:prd.md
-    ├── clavix:start.md
-    └── clavix:summarize.md
+    ├── clavix/
+    │   ├── fast.md
+    │   ├── deep.md
+    │   ├── prd.md
+    │   ├── plan.md
+    │   ├── implement.md
+    │   ├── start.md
+    │   └── summarize.md
 ```
 
 ## Configuration

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

@@ -2,10 +2,16 @@ import { Command } from '@oclif/core';
 export default class Deep extends Command {
     static description: string;
     static examples: string[];
+    static flags: {
+        'clear-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'framework-info': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
     static args: {
         prompt: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<void>;
     private displayOutput;
+    private displayCLEAROnlyAnalysis;
+    private displayFrameworkInfo;
 }
 //# sourceMappingURL=deep.d.ts.map

package/dist/cli/commands/deep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/deep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAQ,MAAM,aAAa,CAAC;AAI5C,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IACvC,MAAM,CAAC,WAAW,SAAqD;IAEvE,MAAM,CAAC,QAAQ,WAGb;IAEF,MAAM,CAAC,IAAI;;MAKT;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB1B,OAAO,CAAC,aAAa;CAsHtB"}
+{"version":3,"file":"deep.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/deep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAe,MAAM,aAAa,CAAC;AAInD,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IACvC,MAAM,CAAC,WAAW,SAAuH;IAEzI,MAAM,CAAC,QAAQ,WAGb;IAEF,MAAM,CAAC,KAAK;;;MASV;IAEF,MAAM,CAAC,IAAI;;MAKT;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAmC1B,OAAO,CAAC,aAAa;IAwIrB,OAAO,CAAC,wBAAwB;IA8EhC,OAAO,CAAC,oBAAoB;CAwD7B"}