clavix 2.3.0 → 2.4.0

package/dist/utils/template-loader.js

@@ -36,40 +36,42 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadCommandTemplates = loadCommandTemplates;
 const path = __importStar(require("path"));
 const file_system_1 = require("./file-system");
-const toml_templates_1 = require("./toml-templates");
 async function loadCommandTemplates(adapter) {
-    const templatesDir = getTemplatesDirectory(adapter.name);
+    // Load from canonical template source (always .md files)
+    const templatesDir = getCanonicalTemplatesDirectory();
     const files = await file_system_1.FileSystem.listFiles(templatesDir);
     if (files.length === 0) {
         return [];
     }
-    const extension = adapter.fileExtension;
-    const commandFiles = files.filter((file) => file.endsWith(extension));
+    // Canonical templates are always .md files
+    const commandFiles = files.filter((file) => file.endsWith('.md'));
     const templates = [];
     for (const file of commandFiles) {
         const templatePath = path.join(templatesDir, file);
         const content = await file_system_1.FileSystem.readFile(templatePath);
-        const name = file.slice(0, -extension.length);
-        if (extension === '.toml') {
-            const parsed = (0, toml_templates_1.parseTomlSlashCommand)(content, name, adapter.name);
-            templates.push({
-                name,
-                content: parsed.prompt,
-                description: parsed.description,
-            });
-        }
-        else {
-            templates.push({
-                name,
-                content,
-                description: extractDescription(content),
-            });
-        }
+        const name = file.slice(0, -3); // Remove .md extension
+        // Extract description and clean content from markdown
+        const description = extractDescription(content);
+        const cleanContent = stripFrontmatter(content);
+        templates.push({
+            name,
+            content: cleanContent,
+            description,
+        });
     }
     return templates;
 }
-function getTemplatesDirectory(adapterName) {
-    return path.join(__dirname, '..', 'templates', 'slash-commands', adapterName);
+function getCanonicalTemplatesDirectory() {
+    return path.join(__dirname, '..', 'templates', 'slash-commands', '_canonical');
+}
+/**
+ * Strip YAML frontmatter from markdown content
+ * Returns clean content without the --- delimited frontmatter
+ */
+function stripFrontmatter(content) {
+    // Match YAML frontmatter pattern: ---\n...\n---
+    const frontmatterRegex = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+    return content.replace(frontmatterRegex, '').trim();
 }
 function extractDescription(content) {
     const yamlMatch = content.match(/description:\s*(.+)/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "2.3.0",
+  "version": "2.4.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",

package/dist/templates/slash-commands/augment/archive.md

@@ -1,291 +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. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION**
-   ```bash
-   clavix archive [project-name] --delete
-   ```
-
-   **WARNING**: This PERMANENTLY deletes the project. Cannot be restored.
-
-   **When to delete vs archive:**
-   - **DELETE**: Failed experiments, duplicate projects, test/demo data, abandoned prototypes with no value
-   - **ARCHIVE**: Completed work, incomplete but potentially useful work, anything you might reference later
-
-   **Delete decision tree:**
-   ```
-   Is this a failed experiment with no learning value? → DELETE
-   Is this a duplicate/test project with no unique info? → DELETE
-   Might you need to reference this code later? → ARCHIVE
-   Could this be useful for learning/reference? → ARCHIVE
-   Are you unsure? → ARCHIVE (safe default)
-   ```
-
-   **Safety confirmation required:**
-   - Shows project details and task status
-   - Requires typing project name to confirm
-   - Warns about permanent deletion
-   - Lists what will be permanently deleted
-
-6. **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/
-```
-
-### Workflow 4: Delete Failed Experiment
-```
-User: "I have a test project 'api-experiment-1' that I don't need anymore"
-You: "Is this something you might reference later, or can it be permanently deleted?"
-
-User: "It was just a quick test, no value. Delete it."
-You: "This will permanently delete the project. I'll run the delete command."
-
-     Run: clavix archive api-experiment-1 --delete
-
-System shows:
-  Project: api-experiment-1
-  Tasks: 3/5 completed
-  Files: full-prd.md, quick-prd.md, tasks.md
-
-  WARNING: This action is PERMANENT and CANNOT be undone.
-  Type the project name to confirm deletion: _
-
-User types: api-experiment-1
-
-Result: Project permanently deleted from .clavix/outputs/api-experiment-1/
-```
-
-## 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
-
-5. **Handle delete requests carefully**:
-   - Always ask if they want to delete or archive
-   - Explain that delete is permanent and irreversible
-   - Suggest archive as the safer default
-   - Use decision tree to help user decide
-   - Only proceed with `--delete` after clear confirmation
-   - Double-check it's truly no-value content (failed experiments, duplicates)
-
-## Workflow Navigation
-
-**You are here:** Archive (Project Cleanup)
-
-**Common workflows:**
-- **Complete workflow**: `/clavix:implement` → [all tasks done] → `/clavix:archive` → Clean workspace
-- **Review and archive**: `/clavix:archive` → [select completed project] → Archive
-- **Restore old work**: `/clavix:archive --list` → `/clavix:archive --restore [project]` → Resume
-
-**Related commands:**
-- `/clavix:implement` - Complete remaining tasks before archiving
-- `/clavix:plan` - Review task completion status
-- `/clavix:prd` - Start new project after archiving old one
-
-## 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
-
-## Troubleshooting
-
-### Issue: No projects available to archive
-**Cause**: No projects in `.clavix/outputs/` OR all already archived
-**Solution**:
-- Run `clavix archive --list` to see archived projects
-- Check `.clavix/outputs/` for active projects
-- If none exist, no action needed
-
-### Issue: Trying to archive project with incomplete tasks
-**Cause**: User wants to archive but tasks aren't 100% done
-**Solution** (inline):
-- Warn: "Project has X incomplete tasks. Archive anyway?"
-- Show which tasks are incomplete
-- Suggest `--force` flag if user confirms
-- Recommend completing tasks first if they're actually unfinished (not scope-changed)
-
-### Issue: Cannot restore archived project (name conflict)
-**Cause**: Project with same name already exists in active outputs
-**Solution**:
-- Error: "Project '[name]' already exists in active outputs"
-- Suggest renaming one of them
-- Or archive the active one first, then restore
-- Or restore to different name (if CLI supports it)
-
-### Issue: Unsure whether to delete or archive
-**Cause**: User wants to clean up but uncertain about permanence
-**Solution**:
-- Use the decision tree in template
-- Default recommendation: ARCHIVE (safer)
-- Only suggest delete for: duplicates, failed experiments, test data
-- Remind: Archive is free, disk space is cheap, regret is expensive
-
-### Issue: Accidentally deleted project (used --delete instead of archive)
-**Cause**: User error or misunderstanding of --delete flag
-**Solution**:
-- Cannot be recovered from Clavix
-- Check if git history exists (if code was committed)
-- Check if user has backups
-- Learn: Use archive by default, delete only when absolutely certain
-
-### Issue: Archive directory getting too large
-**Cause**: Many archived projects accumulating
-**Solution**:
-- Archive is meant to grow - this is normal
-- Projects in archive don't affect performance
-- If truly concerned: Review archive, delete ancient/irrelevant projects
-- Or move very old archives to external backup storage
-
-### Issue: Archived project but forgot what it was about
-**Cause**: No naming convention or time passed
-**Solution**:
-- Read PRD in archived project: `.clavix/outputs/archive/[project]/full-prd.md`
-- PRD contains problem, goal, and features
-- Consider better naming conventions: date-feature format (e.g., "2024-01-user-auth")

package/dist/templates/slash-commands/augment/deep.md

@@ -1,207 +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. **Strategic Scope Detection** (before detailed analysis):
-
-   **Check for strategic concerns** by identifying keywords/themes:
-   - **Architecture**: system design, microservices, monolith, architecture patterns, scalability patterns
-   - **Security**: authentication, authorization, encryption, security, OWASP, vulnerabilities, threat model
-   - **Scalability**: load balancing, caching, database scaling, performance optimization, high availability
-   - **Infrastructure**: deployment, CI/CD, DevOps, cloud infrastructure, containers, orchestration
-   - **Business Impact**: ROI, business metrics, KPIs, stakeholder impact, market analysis
-
-   **If 3+ strategic keywords detected**:
-   Ask the user: "I notice this involves strategic decisions around [detected themes]. These topics benefit from PRD-style planning with business context and architectural considerations. Would you like to:
-   - Switch to `/clavix:prd` for comprehensive strategic planning (recommended)
-   - Continue with deep mode for prompt-level analysis only"
-
-   **If user chooses to continue**, proceed with deep analysis but remind them at the end that `/clavix:prd` is available for strategic planning.
-
-4. **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
-
-## Workflow Navigation
-
-**You are here:** Deep Mode (Comprehensive CLEAR Analysis)
-
-**Common workflows:**
-- **Thorough analysis**: `/clavix:deep` → Use optimized prompt + alternatives
-- **Escalate to strategic**: `/clavix:deep` → (detects strategic scope) → `/clavix:prd` → Plan → Implement → Archive
-- **From fast mode**: `/clavix:fast` → (suggests) `/clavix:deep` → Full analysis with A & R components
-
-**Related commands:**
-- `/clavix:fast` - Quick CLEAR improvements (C, L, E only)
-- `/clavix:prd` - Strategic PRD generation for architecture/business decisions
-- `/clavix:start` - Conversational mode for exploring unclear requirements
-
-## 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`
-
-## Troubleshooting
-
-### Issue: Strategic scope detected but user wants to continue with deep mode
-**Cause**: User prefers deep analysis over PRD generation
-**Solution**:
-- Proceed with deep mode as requested
-- Remind at end that `/clavix:prd` is available for strategic planning
-- Focus on prompt-level CLEAR analysis, exclude architecture recommendations
-
-### Issue: Too many alternative variations making output overwhelming
-**Cause**: Adaptive component generating many options
-**Solution**:
-- Limit to 2-3 most distinct alternatives
-- Focus on meaningfully different approaches (not minor wording changes)
-- Group similar variations together
-
-### Issue: Reflective validation finding too many edge cases
-**Cause**: Complex prompt with many potential failure modes
-**Solution**:
-- Prioritize most likely or highest-impact edge cases
-- Group related edge cases
-- Suggest documenting all edge cases in PRD for complex projects
-
-### Issue: Deep analysis still feels insufficient for complex project
-**Cause**: Project needs strategic planning, not just prompt analysis
-**Solution**:
-- Switch to `/clavix:prd` for comprehensive planning
-- Deep mode is for prompts, PRD mode is for projects
-- Use PRD workflow: PRD → Plan → Implement