clavix 4.2.0 → 4.3.2

package/dist/templates/instructions/core 2/verification.md

@@ -1,377 +0,0 @@
-# Verification & Checkpoint Patterns
-
-## Overview
-
-Verification ensures that critical workflow steps actually completed successfully. This document provides patterns for adding checkpoints and validation to Clavix workflows.
-
----
-
-## Checkpoint Markers
-
-### What Are Checkpoints?
-
-Checkpoints are standardized markers that agents output to confirm workflow step completion. They enable:
-- Progress tracking
-- Failure detection
-- Workflow validation
-- Debugging
-
-### Checkpoint Format
-
-```markdown
-**CHECKPOINT:** [Brief description of what was completed]
-```
-
-### Examples
-
-```markdown
-**CHECKPOINT:** Entered conversational mode (gathering requirements only)
-**CHECKPOINT:** Asked 5 clarifying questions about authentication system
-**CHECKPOINT:** Extracted requirements from conversation
-**CHECKPOINT:** Created 3 output files successfully
-**CHECKPOINT:** Files verified - all exist at expected paths
-```
-
----
-
-## When to Add Checkpoints
-
-### 1. Mode Transitions
-
-**When entering a specific mode:**
-```markdown
-**CHECKPOINT:** Entered conversational mode for requirements gathering
-**CHECKPOINT:** Started PRD generation workflow
-**CHECKPOINT:** Beginning deep analysis of prompt
-```
-
-### 2. After File Operations
-
-**After creating files:**
-```markdown
-**CHECKPOINT:** Files created successfully - verified existence
-**CHECKPOINT:** Saved prompt to .clavix/outputs/prompts/fast/fast-20251124-1430.md
-```
-
-### 3. After Complex Operations
-
-**After multi-step processes:**
-```markdown
-**CHECKPOINT:** Completed Clavix Intelligence™ optimization - 5 improvements applied
-**CHECKPOINT:** Analyzed conversation - extracted 12 requirements, 3 constraints
-```
-
-### 4. At Decision Points
-
-**When making workflow decisions:**
-```markdown
-**CHECKPOINT:** Conversation complexity threshold reached (15+ exchanges) - suggesting summarization
-**CHECKPOINT:** Missing critical requirements - requesting more information before proceeding
-```
-
----
-
-## Verification Patterns
-
-### Pattern 1: File Existence Verification
-
-**After file creation, always verify:**
-
-```markdown
-**Step 5: Verify File Creation**
-
-List the created files to confirm they exist:
-```
-Created files:
-✓ .clavix/outputs/[project]/mini-prd.md
-✓ .clavix/outputs/[project]/original-prompt.md
-✓ .clavix/outputs/[project]/optimized-prompt.md
-```
-
-**CHECKPOINT:** All files created successfully.
-
-If any file is missing:
-- Review file creation steps
-- See troubleshooting: `.clavix/instructions/troubleshooting/skipped-file-creation.md`
-```
-
----
-
-### Pattern 2: Content Validation
-
-**Verify content meets requirements:**
-
-```markdown
-**Step 6: Validate Content**
-
-Verify each file contains:
-- ✓ mini-prd.md: Objective, Requirements, Constraints, Success Criteria sections
-- ✓ original-prompt.md: At least 2 paragraphs of extracted requirements
-- ✓ optimized-prompt.md: Improvements labeled with [ADDED], [CLARIFIED], etc.
-
-**CHECKPOINT:** Content validation passed.
-```
-
----
-
-### Pattern 3: Mode Boundary Verification
-
-**Verify agent stayed in correct mode:**
-
-```markdown
-**Step 7: Mode Compliance Check**
-
-Confirm you stayed in CLAVIX MODE:
-- ✓ Did NOT implement application code
-- ✓ Did NOT generate feature implementations
-- ✓ Only created planning documents and prompts
-
-**CHECKPOINT:** Mode boundaries respected.
-```
-
----
-
-### Pattern 4: Requirement Completeness
-
-**Verify minimum requirements gathered:**
-
-```markdown
-**Pre-Extraction Validation**
-
-Before proceeding with summarization, verify conversation includes:
-- ✓ Clear project objective (what are we building?)
-- ✓ At least 3 core requirements
-- ✓ Technical constraints or framework preferences (if applicable)
-
-If ANY are missing:
-- DO NOT proceed with summarization
-- Ask clarifying questions to gather missing information
-- Reference: `.clavix/instructions/troubleshooting/incomplete-requirements.md`
-
-**CHECKPOINT:** Minimum requirements met - proceeding with extraction.
-```
-
----
-
-## Self-Correction Patterns
-
-### Detecting Premature Implementation
-
-```markdown
-**Self-Check: Am I Implementing?**
-
-If you catch yourself:
-- Writing application code (functions, components, classes)
-- Implementing features being discussed
-- Generating code examples for the actual feature
-
-**IMMEDIATE ACTION:**
-1. STOP writing implementation code
-2. Delete the implementation attempt
-3. Output: "I apologize - I was jumping to implementation. Let me return to requirements gathering."
-4. Return to asking clarifying questions
-5. Reference: `.clavix/instructions/core/clavix-mode.md`
-
-**CHECKPOINT:** Self-corrected - returned to requirements mode.
-```
-
----
-
-### Detecting Skipped Steps
-
-```markdown
-**Self-Check: Did I Skip File Creation?**
-
-Before completing the summarization workflow, verify:
-- ✓ Created .clavix/outputs/[project]/ directory
-- ✓ Wrote mini-prd.md
-- ✓ Wrote original-prompt.md
-- ✓ Wrote optimized-prompt.md
-- ✓ Verified all files exist
-
-If any step was skipped:
-1. Go back and complete missing steps
-2. Reference: `.clavix/instructions/core/file-operations.md`
-3. Verify files exist before marking workflow complete
-
-**CHECKPOINT:** All file creation steps completed.
-```
-
----
-
-## Troubleshooting Detection
-
-### Pattern: Identify Common Failures
-
-```markdown
-**Troubleshooting Check**
-
-If workflow isn't proceeding as expected, check:
-
-1. **Files not created?**
-   - See: `.clavix/instructions/troubleshooting/skipped-file-creation.md`
-   - Common cause: Used "suggest saving" instead of explicit Write tool steps
-
-2. **Jumped to implementation?**
-   - See: `.clavix/instructions/troubleshooting/jumped-to-implementation.md`
-   - Common cause: Didn't see CLAVIX MODE boundary or mode enforcement
-
-3. **Conversation not progressing?**
-   - See: `.clavix/instructions/troubleshooting/mode-confusion.md`
-   - Common cause: Unclear which mode (planning vs implementation) is active
-
-**CHECKPOINT:** Troubleshooting guidance provided if needed.
-```
-
----
-
-## Verification in Specific Workflows
-
-### Conversational Mode (/clavix:start)
-
-```markdown
-**Checkpoints to include:**
-
-1. After entering mode:
-   **CHECKPOINT:** Entered conversational mode (gathering requirements only)
-
-2. After asking questions:
-   **CHECKPOINT:** Asked [N] clarifying questions about [topic]
-
-3. At complexity threshold:
-   **CHECKPOINT:** Complexity threshold reached - suggesting /clavix:summarize
-
-4. Before any implementation attempt:
-   **SELF-CHECK:** Am I about to implement? If yes, STOP and return to questions.
-
-5. When user says "summarize":
-   **CHECKPOINT:** Transitioning to summarization workflow
-```
-
----
-
-### Summarization (/clavix:summarize)
-
-```markdown
-**Checkpoints to include:**
-
-1. Before extraction:
-   **CHECKPOINT:** Pre-extraction validation passed - minimum requirements present
-
-2. After extraction:
-   **CHECKPOINT:** Extracted [N] requirements, [M] constraints from conversation
-
-3. Before file creation:
-   **CHECKPOINT:** Beginning file creation (3 files required)
-
-4. After each file:
-   **CHECKPOINT:** Created mini-prd.md successfully
-   **CHECKPOINT:** Created original-prompt.md successfully
-   **CHECKPOINT:** Created optimized-prompt.md successfully
-
-5. After verification:
-   **CHECKPOINT:** All files verified - exist at expected paths
-
-6. After optimization:
-   **CHECKPOINT:** Applied Clavix Intelligence™ - [N] improvements added
-
-7. Workflow complete:
-   **CHECKPOINT:** Summarization workflow complete - all outputs created
-```
-
----
-
-### Quick Improvement (/clavix:fast)
-
-```markdown
-**Checkpoints to include:**
-
-1. After analysis:
-   **CHECKPOINT:** Analyzed prompt - identified [N] improvement areas
-
-2. After optimization:
-   **CHECKPOINT:** Generated optimized prompt with [N] enhancements
-
-3. After file creation:
-   **CHECKPOINT:** Saved prompt to .clavix/outputs/prompts/fast/[id].md
-
-4. After verification:
-   **CHECKPOINT:** File verified - prompt saved successfully
-```
-
----
-
-### Deep Analysis (/clavix:deep)
-
-```markdown
-**Checkpoints to include:**
-
-1. After initial analysis:
-   **CHECKPOINT:** Completed deep analysis - generated [N] alternative phrasings
-
-2. After edge case analysis:
-   **CHECKPOINT:** Identified [M] edge cases and potential issues
-
-3. After file creation:
-   **CHECKPOINT:** Created comprehensive analysis document
-
-4. After verification:
-   **CHECKPOINT:** All outputs verified - deep analysis complete
-```
-
----
-
-## Integration with Runtime Validation (Future)
-
-### Checkpoint Format for Parsing
-
-Use consistent format to enable future automated validation:
-
-```markdown
-**CHECKPOINT:** <status> - <description>
-
-Where:
-- <status>: SUCCESS, WARNING, ERROR, INFO
-- <description>: What was completed or detected
-
-Examples:
-**CHECKPOINT:** SUCCESS - Files created and verified
-**CHECKPOINT:** WARNING - Complexity threshold reached
-**CHECKPOINT:** ERROR - Missing required information
-**CHECKPOINT:** INFO - Entered conversational mode
-```
-
-### Future Enhancements
-
-- Parse checkpoint markers from agent output
-- Detect missing expected checkpoints
-- Validate workflow completion
-- Generate workflow reports
-- Identify common failure patterns
-
----
-
-## Summary
-
-**Always include:**
-1. **Checkpoints** after major workflow steps
-2. **Verification steps** for file operations
-3. **Self-correction checks** at decision points
-4. **Troubleshooting detection** for common failures
-
-**Format:**
-```markdown
-**CHECKPOINT:** [Clear description of what completed]
-```
-
-**Use verification to:**
-- Confirm files created
-- Validate content structure
-- Ensure mode boundaries respected
-- Detect and correct failures
-
-**Reference troubleshooting guides when:**
-- Files not created
-- Implementation occurred prematurely
-- Mode confusion detected
-- Requirements incomplete

package/dist/templates/instructions/troubleshooting 2/jumped-to-implementation.md

@@ -1,234 +0,0 @@
-# Troubleshooting: Agent Jumped to Implementation
-
-## Problem Description
-
-Agent started implementing the feature instead of staying in requirements/planning mode during Clavix workflows.
-
----
-
-## Symptoms
-
-- Agent generated application code during `/clavix:start` conversational mode
-- Agent created functions, components, or classes for the feature being discussed
-- Agent built implementation examples instead of asking clarifying questions
-- Agent jumped from requirements gathering to coding without explicit user request
-
----
-
-## Why This Happens
-
-**Root causes:**
-
-1. **Missing CLAVIX MODE boundary** - Agent didn't see or internalize the "DO NOT IMPLEMENT" instruction
-2. **Default helpfulness** - Agents are trained to be helpful, which often means "solve the problem" = implement
-3. **Implicit mode boundaries** - "Stay in conversational mode" is too subtle without explicit gates
-4. **Premature optimization** - Agent thinks "I have enough info to implement" after 1-2 questions
-
----
-
-## Immediate Fix
-
-If an agent has already jumped to implementation:
-
-### Step 1: Stop Implementation
-
-Agent should:
-1. **STOP** writing implementation code immediately
-2. **Delete** or discard the implementation attempt
-3. **Acknowledge** the mistake
-
-### Step 2: Apologize and Correct
-
-Agent should output:
-
-```markdown
-I apologize - I was jumping to implementation prematurely.
-
-I'm in Clavix mode, which is for requirements gathering and planning, NOT for implementing features yet.
-
-Let me return to asking clarifying questions about your requirements instead.
-```
-
-### Step 3: Return to Correct Mode
-
-Agent should:
-1. **Return** to asking clarifying questions (if in `/clavix:start`)
-2. **Return** to extracting requirements (if in `/clavix:summarize`)
-3. **Return** to analyzing prompts (if in `/clavix:fast` or `/clavix:deep`)
-4. **Return** to generating PRD (if in `/clavix:prd`)
-
-**NOT** continue with implementation.
-
----
-
-## Prevention Strategies
-
-### For Template Authors
-
-**1. Add CLAVIX MODE Block at Top**
-
-Every workflow template should start with:
-
-```markdown
-## CLAVIX MODE: Requirements & Planning Only
-
-**You are in Clavix prompt/PRD development mode. You help create planning documents, NOT implement features.**
-
-**YOUR ROLE:**
-- ✓ [What you should do]
-
-**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
-
-**ONLY implement if user explicitly says: "Now implement this"**
-```
-
-**2. Repeat Mode Boundaries**
-
-Don't rely on seeing it once. Repeat critical boundaries:
-- At workflow start
-- Before agent might implement (e.g., after questions in conversational mode)
-- In troubleshooting sections
-- At least 3 times in different locations
-
-**3. Add Self-Correction Triggers**
-
-Include explicit checks:
-
-```markdown
-**Self-Check: Am I Implementing?**
-
-If you catch yourself writing application code, STOP IMMEDIATELY.
-1. Delete the implementation
-2. Apologize
-3. Return to requirements mode
-```
-
-**4. Use Explicit Imperative Language**
-
-✓ "DO NOT write code"
-✓ "DO NOT implement features"
-✓ "Your role is requirements gathering, NOT execution"
-
-✗ "Stay in conversational mode" (too subtle)
-✗ "You are gathering requirements" (descriptive, not imperative)
-
----
-
-### For Users
-
-**1. Set Clear Expectations Upfront**
-
-When starting a Clavix workflow, remind the agent:
-
-```markdown
-/clavix:start
-
-Remember: We're just gathering requirements and planning. Don't implement anything yet - I'll ask you to build it later once we have a solid plan.
-```
-
-**2. Catch Early and Redirect**
-
-If agent starts implementing:
-
-```markdown
-Hold on - I don't want implementation yet. I just want to plan and document requirements first.
-
-Let's stay in planning mode. Ask me more questions about what I need.
-```
-
-**3. Explicit Implementation Request**
-
-When you DO want implementation:
-
-```markdown
-Great PRD! Now implement this feature based on the PRD we created.
-```
-
-Be explicit. "Now implement" or "Build this" makes it clear.
-
----
-
-## Testing for This Issue
-
-### Test Scenario 1: Conversational Mode
-
-**Setup:**
-```markdown
-User: /clavix:start
-User: I want to build a todo app with authentication
-```
-
-**Expected behavior:**
-- Agent asks clarifying questions
-- Agent does NOT generate code
-- Agent stays in requirements gathering mode
-
-**Failure indicator:**
-- Agent generates TodoApp component or authentication code
-
----
-
-### Test Scenario 2: After Few Questions
-
-**Setup:**
-```markdown
-User: /clavix:start
-User: I want real-time notifications in my app
-Agent: [Asks 2-3 questions]
-User: [Answers questions]
-```
-
-**Expected behavior:**
-- Agent asks more questions to deepen understanding
-- Agent does NOT implement WebSockets or notification system
-
-**Failure indicator:**
-- Agent generates implementation after thinking "I have enough info"
-
----
-
-## Related Issues
-
-- **Mode Confusion**: See `mode-confusion.md` if agent is unclear which mode is active
-- **Premature Completion**: Agent finishing workflows too early
-- **Missing Checkpoints**: Agent skipping validation steps
-
----
-
-## Success Indicators
-
-Agent is working correctly when:
-- ✓ Agent asks 5+ clarifying questions before considering summarization
-- ✓ Agent never generates application code during Clavix workflows (unless explicitly requested)
-- ✓ Agent explicitly states "I'm in planning mode" or similar acknowledgment
-- ✓ Agent suggests `/clavix:summarize` instead of jumping to implementation
-- ✓ Agent asks "Should I implement or continue planning?" when uncertain
-
----
-
-## Quick Reference
-
-**If agent implements during Clavix workflow:**
-
-1. **Stop** - Agent stops generating code
-2. **Apologize** - "I apologize, I was jumping to implementation..."
-3. **Return** - Go back to requirements/planning mode
-4. **Reference** - Point to CLAVIX MODE boundary in instructions
-
-**Prevention checklist:**
-- ✓ CLAVIX MODE block at top of workflow
-- ✓ "DO NOT IMPLEMENT" repeated 3+ times
-- ✓ Self-correction triggers included
-- ✓ Explicit user request required for implementation
-- ✓ Mode boundaries use imperative language
-
----
-
-## See Also
-
-- `.clavix/instructions/core/clavix-mode.md` - Complete mode boundary explanation
-- `.clavix/instructions/workflows/start.md` - Conversational mode workflow
-- `.clavix/instructions/troubleshooting/mode-confusion.md` - When agent is unclear about mode