clavix 2.1.2 → 2.3.0

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

@@ -9,15 +9,35 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Instructions
 
-1. Review the entire conversation and identify:
-   - **Problem/Goal**: What is the user trying to build or solve?
-   - **Key Requirements**: What features and functionality were discussed?
-   - **Technical Constraints**: Any technologies, integrations, or performance needs?
-   - **User Needs**: Who are the end users and what do they need?
-   - **Success Criteria**: How will success be measured?
-   - **Context**: Any important background or constraints?
-
-2. Generate TWO outputs:
+1. **Pre-Extraction Validation** - Check conversation completeness:
+
+   **Minimum viable requirements:**
+   - **Objective/Goal**: Is there a clear problem or goal stated?
+   - **Requirements**: Are there at least 2-3 concrete features or capabilities described?
+   - **Context**: Is there enough context about who/what/why?
+
+   **If missing critical elements:**
+   - Identify what's missing (e.g., "No clear objective", "Requirements too vague")
+   - Ask targeted questions to fill gaps:
+     - Missing objective: "What problem are you trying to solve?"
+     - Vague requirements: "Can you describe 2-3 specific things this should do?"
+     - No context: "Who will use this and in what situation?"
+   - **DO NOT** proceed to extraction until minimum viable requirements met
+
+   **Confidence indicators** (annotate extracted elements):
+   - **[HIGH]**: Explicitly stated multiple times with details
+   - **[MEDIUM]**: Mentioned once or inferred from context
+   - **[LOW]**: Assumed based on limited information
+
+2. Review the entire conversation and identify (with confidence indicators):
+   - **Problem/Goal** [confidence]: What is the user trying to build or solve?
+   - **Key Requirements** [confidence per requirement]: What features and functionality were discussed?
+   - **Technical Constraints** [confidence]: Any technologies, integrations, or performance needs?
+   - **User Needs** [confidence]: Who are the end users and what do they need?
+   - **Success Criteria** [confidence]: How will success be measured?
+   - **Context** [confidence]: Any important background or constraints?
+
+3. Generate TWO outputs:
 
    **Mini-PRD** (structured document):
    ```markdown
@@ -52,12 +72,18 @@ You are analyzing the conversation history and extracting optimized requirements
    [Success criteria and any important context]
    ```
 
-3. **CLEAR Framework Optimization** (automatic):
-   - After extracting the optimized prompt, it's analyzed using CLEAR framework
-   - Applies Conciseness, Logic, and Explicitness enhancements
-   - Displays both raw extraction and CLEAR-enhanced version
-   - Shows CLEAR scores and improvements made
-   - Saves CLEAR-optimized version as `clear-optimized-prompt.md`
+3. **CLEAR Framework Optimization** (automatic with labeled improvements):
+   - After extracting the optimized prompt, analyze using CLEAR framework
+   - Apply Conciseness, Logic, and Explicitness enhancements
+   - **Label all improvements** with CLEAR component tags:
+     - **[C]**: "Removed 12 conversational words, reduced from 45 to 28 words"
+     - **[L]**: "Restructured flow: context → requirements → constraints → success criteria"
+     - **[E]**: "Added explicit output format (React component), persona (senior dev), success metrics (load time < 2s)"
+   - Display both raw extraction and CLEAR-enhanced version
+   - Show CLEAR scores (before/after) and labeled improvements
+   - Save both versions:
+     - `optimized-prompt.md` (raw extraction)
+     - `clear-optimized-prompt.md` (CLEAR-enhanced with improvement notes)
 
 4. Highlight key insights discovered during the conversation.
 
@@ -78,12 +104,26 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Quality Checks
 
-- ✅ Clear objective stated
-- ✅ Specific, actionable requirements
-- ✅ Technical constraints identified
-- ✅ Success criteria defined
-- ✅ User needs considered
-- ✅ CLEAR framework applied for AI consumption
+- Clear objective stated
+- Specific, actionable requirements
+- Technical constraints identified
+- Success criteria defined
+- User needs considered
+- CLEAR framework applied for AI consumption
+
+## Workflow Navigation
+
+**You are here:** Summarize (Conversation Extraction)
+
+**Common workflows:**
+- **Standard flow**: `/clavix:start` → [conversation] → `/clavix:summarize` → Use CLEAR-optimized prompt
+- **To implementation**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
+- **Standalone use**: [Any conversation] → `/clavix:summarize` → Extract and optimize
+
+**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
 
 ## Example
 
@@ -97,3 +137,43 @@ Technical stack: React + TypeScript frontend, integrate with existing Salesforce
 
 Success: Sales managers can identify issues within 30 seconds of opening, dashboard loads in <2 seconds, 90% of team uses it daily within first month.
 ```
+
+## Troubleshooting
+
+### Issue: Pre-extraction validation fails (missing objective/requirements)
+**Cause**: Conversation didn't cover enough detail
+**Solution** (inline - DO NOT extract):
+- List what's missing specifically
+- Ask targeted questions to fill gaps
+- Only proceed to extraction after minimum viable requirements met
+- Show confidence indicators for what WAS discussed
+
+### Issue: Conversation covered multiple unrelated topics
+**Cause**: Exploratory discussion without focus
+**Solution**:
+- Ask user which topic to extract/focus on
+- Or extract all topics separately into different sections
+- Mark multi-topic extraction with [MULTI-TOPIC] indicator
+- Suggest breaking into separate PRDs for each topic
+
+### Issue: CLEAR optimization doesn't significantly improve extracted prompt
+**Cause**: Conversation was already well-structured and detailed
+**Solution**:
+- Minor improvements are normal for good conversations
+- Show CLEAR scores (should be high: >80%)
+- Still provide both versions but note that original extraction was already CLEAR
+
+### Issue: Low confidence indicators across all extracted elements
+**Cause**: Conversation was too vague or high-level
+**Solution** (inline):
+- Don't just extract with [LOW] markers everywhere
+- Ask follow-up questions to increase confidence
+- Or inform user: "Our conversation was exploratory. I recommend `/clavix:start` to go deeper, or `/clavix:prd` for structured planning"
+
+### Issue: Extracted prompt contradicts earlier conversation
+**Cause**: Requirements evolved during conversation
+**Solution**:
+- Use latest/final version of requirements
+- Note that requirements evolved
+- Ask user to confirm which version is correct
+- Suggest starting fresh with `/clavix:prd` if major contradictions exist

package/dist/types/agent.d.ts

@@ -37,5 +37,5 @@ export interface ManagedBlock {
     content: string;
     targetFile: string;
 }
-export type AgentType = 'agents-md' | 'amp' | 'augment' | 'claude-code' | 'cline' | 'codex' | 'codebuddy' | 'copilot' | 'crush' | 'cursor' | 'custom' | 'droid' | 'gemini' | 'kilocode' | 'octo-md' | 'opencode' | 'qwen' | 'roocode' | 'windsurf';
+export type AgentType = 'agents-md' | 'amp' | 'augment' | 'claude-code' | 'cline' | 'codex' | 'codebuddy' | 'copilot-instructions' | 'crush' | 'cursor' | 'custom' | 'droid' | 'gemini' | 'kilocode' | 'octo-md' | 'opencode' | 'qwen' | 'roocode' | 'windsurf';
 //# sourceMappingURL=agent.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clavix",
-  "version": "2.1.2",
-  "description": "AI prompt improvement and PRD generation CLI tool for developers",
+  "version": "2.3.0",
+  "description": "Transform vague ideas into production-ready prompts. CLI tool using the CLEAR framework to analyze, improve, and generate PRDs for AI coding assistants (Claude Code, Cursor, Windsurf, and more)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/dist/core/adapters/copilot-adapter.d.ts

@@ -1,24 +0,0 @@
-import { BaseAdapter } from './base-adapter';
-import { CommandTemplate } from '../../types/agent';
-/**
- * GitHub Copilot CLI adapter (custom agents)
- * Generates agent profiles under .github/agents
- */
-export declare class CopilotAdapter extends BaseAdapter {
-    readonly name = "copilot";
-    readonly displayName = "Copilot CLI";
-    readonly directory = ".github/agents";
-    readonly fileExtension = ".agent.md";
-    readonly features: {
-        supportsSubdirectories: boolean;
-        supportsFrontmatter: boolean;
-        frontmatterFields: string[];
-    };
-    detectProject(): Promise<boolean>;
-    getCommandPath(): string;
-    getTargetFilename(name: string): string;
-    protected formatCommand(template: CommandTemplate): string;
-    private toTitle;
-    private getHomeDir;
-}
-//# sourceMappingURL=copilot-adapter.d.ts.map

package/dist/core/adapters/copilot-adapter.js

@@ -1,88 +0,0 @@
-"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.CopilotAdapter = void 0;
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
-const base_adapter_1 = require("./base-adapter");
-const file_system_1 = require("../../utils/file-system");
-/**
- * GitHub Copilot CLI adapter (custom agents)
- * Generates agent profiles under .github/agents
- */
-class CopilotAdapter extends base_adapter_1.BaseAdapter {
-    constructor() {
-        super(...arguments);
-        this.name = 'copilot';
-        this.displayName = 'Copilot CLI';
-        this.directory = '.github/agents';
-        this.fileExtension = '.agent.md';
-        this.features = {
-            supportsSubdirectories: false,
-            supportsFrontmatter: true,
-            frontmatterFields: ['name', 'description', 'tools', 'target'],
-        };
-    }
-    async detectProject() {
-        if (await file_system_1.FileSystem.exists('.github/agents')) {
-            return true;
-        }
-        const homeAgentsDir = path.join(this.getHomeDir(), '.copilot', 'agents');
-        return file_system_1.FileSystem.exists(homeAgentsDir);
-    }
-    getCommandPath() {
-        return this.directory;
-    }
-    getTargetFilename(name) {
-        return `clavix-${name}${this.fileExtension}`;
-    }
-    formatCommand(template) {
-        const displayName = `Clavix: ${this.toTitle(template.name)}`;
-        const frontmatter = `---\nname: ${displayName}\ndescription: ${template.description}\n---\n\n`;
-        return frontmatter + template.content;
-    }
-    toTitle(value) {
-        return value
-            .split(/[-_\s]+/)
-            .filter(Boolean)
-            .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-            .join(' ');
-    }
-    getHomeDir() {
-        return process.env.CLAVIX_HOME_OVERRIDE || os.homedir();
-    }
-}
-exports.CopilotAdapter = CopilotAdapter;
-//# sourceMappingURL=copilot-adapter.js.map

package/dist/templates/slash-commands/copilot/archive.agent.md

@@ -1,164 +0,0 @@
----
-name: "Clavix: Archive"
-description: Archive completed PRD projects
----
-
-# Clavix Archive - PRD Project Archival
-
-You are helping the user archive completed PRD projects to keep their workspace organized.
-
-## Instructions
-
-1. **Understanding Archive**:
-   - Archives move completed PRD projects from `.clavix/outputs/` to `.clavix/outputs/archive/`
-   - Archived projects are no longer shown in active project lists
-   - Projects can be restored from archive if needed
-   - Only projects with all tasks completed should typically be archived
-
-2. **Interactive Archive Mode**:
-   ```bash
-   clavix archive
-   ```
-
-   This will:
-   - List all PRD projects with 100% tasks completed
-   - Allow user to select which project to archive
-   - Confirm before archiving
-   - Move the project to archive directory
-
-3. **Archive Specific Project**:
-   ```bash
-   clavix archive [project-name]
-   ```
-
-   This will:
-   - Check task completion status
-   - Warn if tasks are incomplete
-   - Ask for confirmation
-   - Archive the specific project
-
-4. **Force Archive (Incomplete Tasks)**:
-   ```bash
-   clavix archive [project-name] --force
-   ```
-
-   Use this when:
-   - Project scope changed and some tasks are no longer relevant
-   - User wants to archive work-in-progress
-   - Tasks are incomplete but project is done
-
-5. **List Archived Projects**:
-   ```bash
-   clavix archive --list
-   ```
-
-   Shows all projects currently in archive with their task completion status
-
-6. **Restore from Archive**:
-   ```bash
-   clavix archive --restore [project-name]
-   ```
-
-   Moves a project back from archive to active outputs
-
-## When to Archive
-
-✅ **Good times to archive**:
-- All implementation tasks are completed (`tasks.md` shows 100%)
-- Project has been deployed/shipped to production
-- Feature is complete and no more work planned
-- User explicitly requests archival
-- Old/abandoned projects that won't be continued
-
-❌ **Don't archive when**:
-- Tasks are still in progress (unless using --force)
-- Project is actively being worked on
-- Future enhancements are planned in current tasks
-
-## Archive Behavior
-
-**What gets archived:**
-- The entire PRD project folder
-- All files: PRD.md, PRD-quick.md, tasks.md, .clavix-implement-config.json
-- Complete directory structure preserved
-
-**Where it goes:**
-- From: `.clavix/outputs/[project-name]/`
-- To: `.clavix/outputs/archive/[project-name]/`
-
-**What changes:**
-- Archived projects won't show in `/clavix:plan` searches
-- Archived projects won't show in `/clavix:implement` searches
-- They're still accessible in archive directory
-- Can be restored at any time
-
-## Example Workflows
-
-### Workflow 1: Complete Project
-```
-User: "I've finished implementing the user authentication feature"
-You: "Great! Let me help you archive it."
-
-     Run: clavix archive
-
-User selects: user-authentication-system
-System shows: All 15 tasks completed (100%)
-User confirms: Yes, archive it
-
-Result: Project moved to .clavix/outputs/archive/user-authentication-system/
-```
-
-### Workflow 2: Force Archive WIP
-```
-User: "We're pivoting, I want to archive the old API design even though tasks aren't done"
-You: "I'll archive it with --force"
-
-     Run: clavix archive old-api-design --force
-
-System shows: 8 incomplete tasks
-User confirms: Yes, archive anyway
-
-Result: Project archived despite incomplete tasks
-```
-
-### Workflow 3: Restore Archived Project
-```
-User: "Actually, we need to revisit that authentication feature"
-You: "I'll restore it from the archive"
-
-     Run: clavix archive --restore user-authentication-system
-
-Result: Project moved back to .clavix/outputs/user-authentication-system/
-```
-
-## AI Agent Guidelines
-
-When user mentions archiving or cleaning up projects:
-
-1. **Check completion status first**:
-   - Run `clavix archive` to see archivable projects
-   - Review task completion percentages
-   - Suggest archiving only completed projects
-
-2. **Confirm before archiving**:
-   - Always confirm which project to archive
-   - Mention the archive location
-   - Explain that it can be restored
-
-3. **Use --force cautiously**:
-   - Only when user explicitly wants to archive incomplete work
-   - Explain which tasks will remain incomplete
-   - Confirm they won't lose data (just moving location)
-
-4. **Suggest restoration**:
-   - If user mentions old work, check archive
-   - Use `clavix archive --list` to show what's archived
-   - Offer to restore if needed
-
-## Tips
-
-- Archive keeps your active projects list clean and focused
-- Archived projects maintain all their data (nothing is deleted)
-- Archive is searchable - you can still `grep` or find files in archive/
-- Regular archiving improves `/clavix:plan` and `/clavix:implement` performance
-- Use `--list` regularly to know what's been archived

package/dist/templates/slash-commands/copilot/deep.agent.md

@@ -1,147 +0,0 @@
----
-name: "Clavix: Deep"
-description: Full CLEAR framework analysis (C, L, E, A, R components)
----
-
-# Clavix Deep Mode - Full CLEAR Framework Analysis
-
-You are helping the user perform a comprehensive deep analysis using the full CLEAR Framework (all 5 components: Concise, Logical, Explicit, Adaptive, Reflective).
-
-## CLEAR Framework (Deep Mode)
-
-**What is CLEAR?**
-An academically-validated prompt engineering framework by Dr. Leo Lo (University of New Mexico).
-
-**Deep Mode Uses ALL Components:**
-- **[C] Concise**: Remove verbosity, pleasantries, unnecessary words
-- **[L] Logical**: Ensure coherent sequencing (context → requirements → constraints → output)
-- **[E] Explicit**: Add persona, format, tone, success criteria
-- **[A] Adaptive**: Generate alternative phrasings, structures, flexibility
-- **[R] Reflective**: Create validation checklists, edge cases, quality criteria
-
-## Instructions
-
-1. Take the user's prompt: `{{ARGS}}`
-
-2. **Apply Full CLEAR Framework** (C, L, E, A, R):
-
-   - **Conciseness [C]**: Detailed verbosity analysis
-   - **Logic [L]**: Comprehensive flow analysis
-   - **Explicitness [E]**: Complete specification check
-   - **Adaptiveness [A]**: Multiple variations and approaches
-   - **Reflectiveness [R]**: Full validation and edge case analysis
-
-3. **Generate Comprehensive Output**:
-
-   a. **📊 CLEAR Assessment** (all 5 components with scores)
-
-   b. **✨ CLEAR-Optimized Prompt** (applying all components)
-
-   c. **📝 CLEAR Changes Made** (labeled with [C], [L], [E], [A], [R])
-
-   d. **🔄 Adaptive Variations [A]**:
-      - 2-3 alternative phrasings
-      - Alternative structures (user story, job story, structured)
-      - Temperature recommendations
-      - Explain when each approach is most appropriate
-
-   e. **🤔 Reflection Checklist [R]**:
-      - Validation steps for accuracy
-      - Edge cases to consider
-      - "What could go wrong" analysis
-      - Fact-checking steps
-      - Quality criteria
-
-4. **CLEAR-labeled educational feedback**:
-   - Label all changes with CLEAR component tags
-   - Example: "[C] Removed 15 unnecessary pleasantries"
-   - Example: "[A] See Alternative Structures for 3 different approaches"
-   - Example: "[R] See Reflection Checklist for 5 validation steps"
-
-5. Present everything in comprehensive, CLEAR-organized format.
-
-## Deep Mode Features
-
-✅ Include (Full CLEAR Framework):
-- **[C, L, E]**: All fast mode analysis (conciseness, logic, explicitness)
-- **[A] Adaptive**: Alternative phrasings, structures, flexibility, temperature
-- **[R] Reflective**: Validation checklist, edge cases, quality criteria, fact-checking
-- **CLEAR Assessment**: All 5 component scores
-- **CLEAR-labeled Changes**: Educational feedback showing which component improved what
-
-❌ Do NOT include (these belong in `/clavix:prd`):
-- System architecture recommendations
-- Security best practices
-- Scalability strategy
-- Business impact analysis
-
-## Example
-
-If user provides: "Create a login page"
-
-Output:
-```
-## Analysis
-[All fast mode analysis: gaps, ambiguities, strengths, suggestions]
-
-## Changes Made
-- Added authentication context and user needs
-- Specified technical stack and constraints
-- Defined success criteria and expected output
-
-## Alternative Phrasings
-1. "Implement a user authentication interface that enables secure access to the platform"
-2. "Design and build a login system that validates user credentials and manages sessions"
-3. "Create an authentication flow that allows registered users to access their accounts"
-
-## Edge Cases to Consider
-- What happens when a user enters incorrect credentials 3+ times?
-- How to handle users who've forgotten both email and password?
-- What about users trying to log in from a new device?
-- How to handle session expiration during active use?
-
-## Implementation Examples
-✅ Good:
-- Prompt specifies authentication method, error handling, and accessibility requirements
-- Includes context about existing auth system and integration points
-- Defines measurable success criteria (load time, accessibility score)
-
-❌ Bad:
-- "Make a login page" - no context, constraints, or success criteria
-- Missing technical stack and integration requirements
-- No consideration of security or user experience
-
-## Alternative Prompt Structures
-1. **User Story**: "As a registered user, I want to log into my account so that I can access my personalized dashboard"
-   → Focuses on user value and benefits
-
-2. **Job Story**: "When I visit the app, I want to authenticate securely, so I can access my saved data"
-   → Emphasizes context and motivation
-
-3. **Structured Sections**: Objective, Requirements, Constraints, Success Criteria
-   → Provides comprehensive organization
-
-## What Could Go Wrong
-- Without security requirements, implementation might miss OWASP best practices
-- Vague "login page" could be interpreted as OAuth, email/password, or social login
-- Missing error handling specification could lead to poor UX
-- No accessibility requirements might exclude users with disabilities
-
-## Improved Prompt
-[Structured prompt with all sections]
-```
-
-## When to Use Deep vs Fast vs PRD
-
-- **Fast mode** (`/clavix:fast`): C, L, E components - quick CLEAR cleanup
-- **Deep mode** (`/clavix:deep`): Full CLEAR (C, L, E, A, R) - comprehensive analysis with alternatives and validation
-- **PRD mode** (`/clavix:prd`): CLEAR-validated PRD generation - strategic planning with architecture decisions
-
-## Tips
-
-- **Apply full CLEAR framework** systematically: all 5 components
-- Label all changes with CLEAR components for education
-- Deep mode focuses on **prompt-level** CLEAR analysis, not strategic architecture
-- Use **[A] Adaptive** to explore alternative approaches
-- Use **[R] Reflective** to identify edge cases and validation needs
-- For architecture, security, and scalability, recommend `/clavix:prd`