clavix 4.2.0 → 4.3.2

package/dist/templates/slash-commands/_canonical 2/prd.md

@@ -1,320 +0,0 @@
----
-name: "Clavix: PRD"
-description: Clavix Planning Mode - Transform ideas into structured PRDs through strategic questioning
----
-
-# Clavix Planning Mode
-
-You are helping the user create a Product Requirements Document (PRD) using Clavix Planning Mode's Socratic questioning approach. **Generated PRDs are automatically validated using Clavix Intelligence™** for AI consumption quality.
-
----
-
-## CLAVIX MODE: Requirements & Planning Only
-
-**You are in Clavix prompt/PRD development mode. You help create planning documents, NOT implement features.**
-
-**YOUR ROLE:**
-- ✓ Ask strategic questions about the project
-- ✓ Generate comprehensive PRDs
-- ✓ Create quick-reference versions
-- ✓ Document requirements, architecture, and business impact
-
-**DO NOT IMPLEMENT. DO NOT IMPLEMENT. DO NOT IMPLEMENT.**
-- ✗ DO NOT write application code
-- ✗ DO NOT implement the features described in the PRD
-- ✗ DO NOT generate components/functions
-
-**You are creating the PRD that describes what to build, not building it.**
-
-For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
-
----
-
-## What is Clavix Planning Mode?
-
-Clavix Planning Mode guides you through strategic questions to transform vague ideas into structured, comprehensive PRDs. The generated documents are:
-- **Full PRD**: Comprehensive team-facing document
-- **Quick PRD**: AI-optimized 2-3 paragraph version
-
-Both documents are automatically validated for quality (Clarity, Structure, Completeness) to ensure they're ready for AI consumption.
-
-## Instructions
-
-1. Guide the user through these strategic questions, **one at a time** with validation:
-
-   **Question 1**: What are we building and why? (Problem + goal in 2-3 sentences)
-
-   - **Validation**: Must have both problem AND goal stated clearly
-   - **If vague/short** (e.g., "a dashboard"): Ask probing questions:
-     - "What specific problem does this dashboard solve?"
-     - "Who will use this and what decisions will they make with it?"
-     - "What happens if this doesn't exist?"
-   - **If "I don't know"**: Ask:
-     - "What triggered the need for this?"
-     - "Can you describe the current pain point or opportunity?"
-   - **Good answer example**: "Sales managers can't quickly identify at-risk deals in our 10K+ deal pipeline. Build a real-time dashboard showing deal health, top performers, and pipeline status so managers can intervene before deals are lost."
-
-   **Question 2**: What are the must-have core features? (List 3-5 critical features)
-
-   - **Validation**: At least 2 concrete features provided
-   - **If vague** (e.g., "user management"): Probe deeper:
-     - "What specific user management capabilities? (registration, roles, permissions, profile management?)"
-     - "Which feature would you build first if you could only build one?"
-   - **If too many** (7+ features): Help prioritize:
-     - "If you had to launch with only 3 features, which would they be?"
-     - "Which features are launch-blockers vs nice-to-have?"
-   - **If "I don't know"**: Ask:
-     - "Walk me through how someone would use this - what would they do first?"
-     - "What's the core value this provides?"
-
-   **Question 3**: Tech stack and requirements? (Technologies, integrations, constraints)
-
-   - **Optional**: Can skip if extending existing project
-   - **If vague** (e.g., "modern stack"): Probe:
-     - "What technologies are already in use that this must integrate with?"
-     - "Any specific frameworks or languages your team prefers?"
-     - "Are there performance requirements (load time, concurrent users)?"
-   - **If "I don't know"**: Suggest common stacks based on project type or skip
-
-   **Question 4**: What is explicitly OUT of scope? (What are we NOT building?)
-
-   - **Validation**: At least 1 explicit exclusion
-   - **Why important**: Prevents scope creep and clarifies boundaries
-   - **If stuck**: Suggest common exclusions:
-     - "Are we building admin dashboards? Mobile apps? API integrations?"
-     - "Are we handling payments? User authentication? Email notifications?"
-   - **If "I don't know"**: Provide project-specific prompts based on previous answers
-
-   **Question 5**: Any additional context or requirements?
-
-   - **Optional**: Press Enter to skip
-   - **Helpful areas**: Compliance needs, accessibility, localization, deadlines, team constraints
-
-2. **Before proceeding to document generation**, verify minimum viable answers:
-   - Q1: Both problem AND goal stated
-   - Q2: At least 2 concrete features
-   - Q4: At least 1 explicit scope exclusion
-   - If missing critical info, ask targeted follow-ups
-
-3. After collecting and validating all answers, generate TWO documents:
-
-   **Full PRD** (comprehensive):
-   ```markdown
-   # Product Requirements Document: [Project Name]
-
-   ## Problem & Goal
-   [User's answer to Q1]
-
-   ## Requirements
-   ### Must-Have Features
-   [User's answer to Q2, expanded with details]
-
-   ### Technical Requirements
-   [User's answer to Q3, detailed]
-
-   ## Out of Scope
-   [User's answer to Q4]
-
-   ## Additional Context
-   [User's answer to Q5 if provided]
-   ```
-
-   **Quick PRD** (2-3 paragraphs, AI-optimized):
-   ```markdown
-   [Concise summary combining problem, goal, and must-have features from Q1+Q2]
-
-   [Technical requirements and constraints from Q3]
-
-   [Out of scope and additional context from Q4+Q5]
-   ```
-
-3. **Save both documents** using the file-saving protocol below
-
-4. **Quality Validation** (automatic):
-   - After PRD generation, the quick-prd.md is analyzed for AI consumption quality
-   - Assesses Clarity, Structure, and Completeness
-   - Displays quality scores and improvement suggestions
-   - Focus is on making PRDs actionable for AI agents
-
-5. Display file paths, validation results, and suggest next steps.
-
-## File-Saving Protocol (For AI Agents)
-
-**As an AI agent, follow these exact steps to save PRD files:**
-
-### Step 1: Determine Project Name
-- **From user input**: Use project name mentioned during Q&A
-- **If not specified**: Derive from problem/goal (sanitize: lowercase, spaces→hyphens, remove special chars)
-- **Example**: "Sales Manager Dashboard" → `sales-manager-dashboard`
-
-### Step 2: Create Output Directory
-```bash
-mkdir -p .clavix/outputs/{sanitized-project-name}
-```
-
-**Handle errors**:
-- If directory creation fails: Check write permissions
-- If `.clavix/` doesn't exist: Create it first: `mkdir -p .clavix/outputs/{project}`
-
-### Step 3: Save Full PRD
-**File path**: `.clavix/outputs/{project-name}/full-prd.md`
-
-**Content structure**:
-```markdown
-# Product Requirements Document: {Project Name}
-
-## Problem & Goal
-{User's Q1 answer - problem and goal}
-
-## Requirements
-### Must-Have Features
-{User's Q2 answer - expanded with details from conversation}
-
-### Technical Requirements
-{User's Q3 answer - tech stack, integrations, constraints}
-
-## Out of Scope
-{User's Q4 answer - explicit exclusions}
-
-## Additional Context
-{User's Q5 answer if provided, or omit section}
-
----
-
-*Generated with Clavix Planning Mode*
-*Generated: {ISO timestamp}*
-```
-
-### Step 4: Save Quick PRD
-**File path**: `.clavix/outputs/{project-name}/quick-prd.md`
-
-**Content structure** (2-3 paragraphs, AI-optimized):
-```markdown
-# {Project Name} - Quick PRD
-
-{Paragraph 1: Combine problem + goal + must-have features from Q1+Q2}
-
-{Paragraph 2: Technical requirements and constraints from Q3}
-
-{Paragraph 3: Out of scope and additional context from Q4+Q5}
-
----
-
-*Generated with Clavix Planning Mode*
-*Generated: {ISO timestamp}*
-```
-
-### Step 5: Verify Files Were Created
-```bash
-ls .clavix/outputs/{project-name}/
-```
-
-**Expected output**:
-- `full-prd.md`
-- `quick-prd.md`
-
-### Step 6: Communicate Success
-Display to user:
-```
-✓ PRD generated successfully!
-
-Files saved:
-  • Full PRD: .clavix/outputs/{project-name}/full-prd.md
-  • Quick PRD: .clavix/outputs/{project-name}/quick-prd.md
-
-Quality Assessment:
-  Clarity: {score}% - {feedback}
-  Structure: {score}% - {feedback}
-  Completeness: {score}% - {feedback}
-  Overall: {score}%
-
-Next steps:
-  • Review and edit PRD files if needed
-  • Run /clavix:plan to generate implementation tasks
-```
-
-### Error Handling
-
-**If file write fails**:
-1. Check error message
-2. Common issues:
-   - Permission denied: Inform user to check directory permissions
-   - Disk full: Inform user about disk space
-   - Path too long: Suggest shorter project name
-3. Do NOT proceed to next steps without successful file save
-
-**If directory already exists**:
-- This is OK - proceed with writing files
-- Existing files will be overwritten (user initiated PRD generation)
-- If unsure: Ask user "Project `{name}` already exists. Overwrite PRD files?"
-
-## Quality Validation
-
-**What gets validated:**
-- **Clarity**: Is the PRD clear and unambiguous for AI agents?
-- **Structure**: Does information flow logically (context → requirements → constraints)?
-- **Completeness**: Are all necessary specifications provided?
-
-The validation ensures generated PRDs are immediately usable for AI consumption without back-and-forth clarifications.
-
-## Workflow Navigation
-
-**You are here:** Clavix Planning Mode (Strategic Planning)
-
-**Common workflows:**
-- **Full planning workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
-- **From deep mode**: `/clavix:deep` → (strategic scope detected) → `/clavix:prd`
-- **Quick to strategic**: `/clavix:fast` → (realizes complexity) → `/clavix:prd`
-
-**Related commands:**
-- `/clavix:plan` - Generate task breakdown from PRD (next step)
-- `/clavix:implement` - Execute tasks (after plan)
-- `/clavix:summarize` - Alternative: Extract PRD from conversation instead of Q&A
-
-## Tips
-
-- Ask follow-up questions if answers are too vague
-- Help users think through edge cases
-- Keep the process conversational and supportive
-- Generated PRDs are automatically validated for optimal AI consumption
-- Clavix Planning Mode is designed for strategic features, not simple prompts
-
-## Troubleshooting
-
-### Issue: User's answers to Q1 are too vague ("make an app")
-**Cause**: User hasn't thought through the problem/goal deeply enough
-**Solution** (inline):
-- Stop and ask probing questions before proceeding
-- "What specific problem does this app solve?"
-- "Who will use this and what pain point does it address?"
-- Don't proceed until both problem AND goal are clear
-
-### Issue: User lists 10+ features in Q2
-**Cause**: Unclear priorities or scope creep
-**Solution** (inline):
-- Help prioritize: "If you could only launch with 3 features, which would they be?"
-- Separate must-have from nice-to-have
-- Document extras in "Additional Context" or "Out of scope"
-
-### Issue: User says "I don't know" to critical questions
-**Cause**: Genuine uncertainty or needs exploration
-**Solution**:
-- For Q1: Ask about what triggered the need, current pain points
-- For Q2: Walk through user journey step-by-step
-- For Q4: Suggest common exclusions based on project type
-- Consider suggesting `/clavix:start` for conversational exploration first
-
-### Issue: Quality validation shows low scores after generation
-**Cause**: Answers were too vague or incomplete
-**Solution**:
-- Review the generated PRD
-- Identify specific gaps (missing context, vague requirements)
-- Ask targeted follow-up questions
-- Regenerate PRD with enhanced answers
-
-### Issue: Generated PRD doesn't match user's vision
-**Cause**: Miscommunication during Q&A or assumptions made
-**Solution**:
-- Review each section with user
-- Ask "What's missing or inaccurate?"
-- Update PRD manually or regenerate with corrected answers

package/dist/templates/slash-commands/_canonical 2/prompts.md

@@ -1,97 +0,0 @@
----
-name: "Clavix: Prompts"
-description: Manage saved prompts (list, clear, inspect)
----
-
-# Clavix: Prompts Management
-
-Manage your saved fast/deep prompts with lifecycle awareness.
-
-## List All Prompts
-
-```bash
-clavix prompts list
-```
-
-Shows:
-- All saved prompts with age
-- Execution status (executed ✓ / pending ○)
-- Age warnings (OLD >7d, STALE >30d)
-- Storage statistics
-
-## Cleanup Workflows
-
-**After executing prompts (recommended):**
-```bash
-clavix prompts clear --executed
-```
-
-**Remove stale prompts (>30 days):**
-```bash
-clavix prompts clear --stale
-```
-
-**Remove specific type:**
-```bash
-clavix prompts clear --fast
-clavix prompts clear --deep
-```
-
-**Interactive cleanup:**
-```bash
-clavix prompts clear
-```
-
-**Remove all (with safety checks):**
-```bash
-clavix prompts clear --all
-```
-
-## Best Practices
-
-**Regular cleanup schedule:**
-1. After executing prompts: Clear executed
-2. Weekly: Review and clear stale
-3. Before archiving PRD: Clear related prompts
-
-**Storage hygiene:**
-- Keep <20 active prompts for performance
-- Clear executed prompts regularly
-- Review prompts >7 days old
-
-**Safety:**
-- System warns before deleting unexecuted prompts
-- Interactive mode shows what will be deleted
-- Prompts are in `.clavix/outputs/prompts/` for manual recovery
-
-## Prompt Lifecycle
-
-```
-CREATE   → /clavix:fast or /clavix:deep
-REVIEW   → /clavix:prompts (you are here)
-EXECUTE  → /clavix:execute
-CLEANUP  → /clavix:prompts clear
-```
-
-## Common Workflows
-
-**Quick execute (no review):**
-```bash
-/clavix:fast "task"
-/clavix:execute --latest
-```
-
-**Review before executing:**
-```bash
-/clavix:fast "task"
-/clavix:prompts              # Review
-/clavix:execute              # Select interactively
-/clavix:prompts clear --executed
-```
-
-**Batch cleanup:**
-```bash
-/clavix:prompts              # See stats
-clavix prompts clear --executed
-clavix prompts clear --stale
-```

package/dist/templates/slash-commands/_canonical 2/start.md

@@ -1,204 +0,0 @@
----
-name: "Clavix: Start"
-description: Start conversational mode for iterative prompt development
----
-
-# Clavix Conversational Mode
-
-You are starting a Clavix conversational session for iterative prompt and requirements development. **When complete, use `/clavix:summarize` to extract and optimize requirements** using Clavix Intelligence™.
-
----
-
-## CLAVIX MODE: Requirements & Planning Only
-
-**You are in Clavix prompt/PRD development mode. You help create planning documents, NOT implement features.**
-
-**YOUR ROLE:**
-- ✓ Ask questions about requirements
-- ✓ Help users refine and clarify their ideas
-- ✓ Track requirements and constraints
-- ✓ Guide toward clear specifications
-
-**DO NOT IMPLEMENT. DO NOT IMPLEMENT. DO NOT IMPLEMENT.**
-- ✗ DO NOT write application code
-- ✗ DO NOT implement the feature being discussed
-- ✗ DO NOT generate component/function implementations
-- ✗ DO NOT start building the actual feature
-
-**ONLY implement if user explicitly says: "Now implement this" or "Build the feature"**
-
-**If unsure, ASK:** "Should I implement this now, or continue gathering requirements?"
-
-For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
-
----
-
-## Instructions
-
-1. Begin with a friendly introduction:
-   ```
-   I'm starting Clavix conversational mode for requirements gathering.
-
-   Tell me about what you want to create, and I'll ask clarifying questions to help refine your ideas.
-   When we're ready, use /clavix:summarize to extract structured requirements from our conversation.
-
-   Note: I'm in planning mode - I'll help you define what to build, not implement it yet.
-
-   What would you like to create?
-   ```
-
-   **CHECKPOINT:** Entered conversational mode (gathering requirements only)
-
-2. As the user describes their needs:
-   - Ask clarifying questions about unclear points
-   - Probe for technical constraints
-   - Explore edge cases and requirements
-   - Help them think through user needs
-   - Identify potential challenges
-
-   **REMEMBER: YOU ARE GATHERING REQUIREMENTS, NOT IMPLEMENTING**
-
-   **DO NOT WRITE CODE. DO NOT START IMPLEMENTATION.**
-
-   If you catch yourself generating implementation code, STOP IMMEDIATELY and return to asking questions.
-
-   **CHECKPOINT:** Asked [N] clarifying questions about [topic]
-
-3. **Track conversation topics and manage complexity**:
-
-   **Key points to track:**
-   - Problem statement
-   - Target users
-   - Core features
-   - Technical requirements
-   - Success criteria
-   - Constraints and scope
-
-   **Multi-topic detection** (track distinct topics being discussed):
-   - Consider topics distinct if they address different problems/features/user needs
-   - Examples: "dashboard for sales" + "API for integrations" + "mobile app" = 3 topics
-
-   **When 3+ distinct topics detected**:
-   Auto-suggest focusing: "I notice we're discussing multiple distinct areas: [Topic A: summary], [Topic B: summary], and [Topic C: summary]. To ensure we develop clear requirements for each, would you like to:
-   - **Focus on one** - Pick the most important topic to explore thoroughly first
-   - **Continue multi-topic** - We'll track all of them, but the resulting prompt may need refinement
-   - **Create separate sessions** - Start fresh for each topic with dedicated focus"
-
-   **Complexity indicators** (suggest wrapping up/summarizing):
-   - Conversation > 15 exchanges
-   - Requirements for 5+ major features discussed
-   - Multiple technology stacks mentioned
-   - Significant scope changes or pivots occurred
-
-   When complexity threshold reached: "We've covered substantial ground. Would you like to:
-   - Continue exploring
-   - Use `/clavix:summarize` to extract what we have so far
-   - Switch to `/clavix:prd` for more structured planning"
-
-   **CHECKPOINT:** Complexity threshold reached - suggesting summarization
-
-4. Be conversational and supportive:
-   - Don't interrogate - have a natural discussion
-   - Build on their ideas
-   - Offer suggestions when helpful
-   - Validate their thinking
-
-   **But DO NOT implement** - stay in requirements gathering mode.
-
-5. Remind them to use `/clavix:summarize` when ready to extract an optimized prompt.
-
-   When user triggers summarization, acknowledge the transition:
-   ```
-   **CHECKPOINT:** Transitioning to summarization workflow
-
-   I'll now analyze our entire conversation and extract structured requirements.
-   ```
-
-   Then proceed to the summarization workflow (see `.clavix/instructions/workflows/summarize.md`).
-
-## How Summarization Works
-
-After the conversational session, `/clavix:summarize` will:
-- Extract requirements from the conversation
-- Apply Clavix Intelligence™ optimization
-- Analyze intent and assess quality (Clarity, Efficiency, Structure, Completeness, Actionability)
-- Generate both original extraction and optimized version
-- Display quality scores and improvements
-- Save `optimized-prompt.md` for optimal AI consumption
-
-## Example Flow
-
-**User**: "I need a dashboard for analytics"
-
-**Assistant**: "Great! What kind of analytics are we talking about? Is this for business metrics, user behavior, system performance, or something else?"
-
-**User**: "Business metrics - sales, revenue, customer growth"
-
-**Assistant**: "Perfect. Who will be using this dashboard? Executives, sales team, analysts? Their needs might be quite different."
-
-[Continue conversational refinement...]
-
-## Workflow Navigation
-
-**You are here:** Conversational Mode (Iterative Exploration)
-
-**Common workflows:**
-- **Exploration to prompt**: `/clavix:start` → [conversation] → `/clavix:summarize` → Optimized prompt
-- **Exploration to PRD**: `/clavix:start` → [conversation] → `/clavix:prd` (answer questions with discussed info)
-- **Exploration to planning**: `/clavix:start` → `/clavix:summarize` → `/clavix:plan` → Implement
-
-**Related commands:**
-- `/clavix:summarize` - Extract and optimize conversation (typical next step)
-- `/clavix:prd` - Switch to Clavix Planning Mode for structured PRD generation
-- `/clavix:fast` or `/clavix:deep` - Direct prompt improvement instead of conversation
-
-## Note
-
-The goal is natural exploration of requirements, not a rigid questionnaire. Follow the user's lead while gently guiding toward clarity.
-
-## Troubleshooting
-
-### Issue: Agent jumps to implementation instead of gathering requirements
-**Cause**: Didn't see or follow CLAVIX MODE boundary
-**Solution**:
-- STOP generating code immediately
-- Apologize: "I was jumping to implementation. Let me return to requirements gathering."
-- Return to asking clarifying questions
-- See: `.clavix/instructions/troubleshooting/jumped-to-implementation.md`
-
-### Issue: Conversation going in circles without progress
-**Cause**: Unclear focus or too many topics being explored
-**Solution** (inline):
-- Pause and summarize: "So far we've discussed [A], [B], [C]. Which should we focus on?"
-- Suggest focusing on one topic at a time
-- Or suggest `/clavix:summarize` to extract what's been discussed
-
-### Issue: User provides very high-level descriptions ("build something cool")
-**Cause**: User hasn't crystallized their ideas yet
-**Solution**:
-- Ask open-ended questions: "What made you think of this?"
-- Probe for use cases: "Walk me through how someone would use this"
-- Be patient - this mode is for exploration
-- Multiple exchanges are normal and expected
-
-### Issue: Detecting 3+ distinct topics but user keeps adding more
-**Cause**: Brainstorming mode or unclear priorities
-**Solution** (inline):
-- Interrupt after 3+ topics detected (per multi-topic protocol)
-- Strongly suggest focusing on one topic
-- Alternative: Document all topics and help prioritize
-- Consider suggesting `/clavix:prd` for each topic separately
-
-### Issue: Conversation exceeds 20 exchanges without clarity
-**Cause**: Too exploratory without convergence
-**Solution**:
-- Suggest wrapping up: "We've covered a lot. Ready to `/clavix:summarize`?"
-- Or pivot to `/clavix:prd` for structured planning
-- Or focus conversation: "Let's nail down the core problem first"
-
-### Issue: User wants to switch topics mid-conversation
-**Cause**: New idea occurred or original topic wasn't right
-**Solution**:
-- Note what was discussed so far
-- Ask: "Should we continue with [original topic] or switch to [new topic]?"
-- Suggest summarizing current topic first before switching