npm - clavix - Versions diffs - 4.2.0 → 4.3.1 - Mend

clavix 4.2.0 → 4.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/dist/templates/instructions/core 2/file-operations.md DELETED Viewed

@@ -1,330 +0,0 @@
-# File Operations: Step-by-Step Patterns
-## Overview
-This guide provides proven patterns for file creation in Clavix workflows. These patterns ensure files are actually created (not just "suggested") and verified.
----
-## The Proven Pattern (Copy This)
-### Complete File Creation Workflow
-```markdown
-**Step 1: Create Directory Structure**
-Use mkdir to create the output directory:
-```bash
-mkdir -p .clavix/outputs/[project-name]
-```
-**Step 2: Write First File**
-Use the Write tool to create `.clavix/outputs/[project-name]/file-name.md` with this content:
-[Provide exact content template here]
-**Step 3: Write Second File**
-Use the Write tool to create `.clavix/outputs/[project-name]/another-file.md` with this content:
-[Provide exact content template here]
-**Step 4: Verify File Creation**
-List the created files to confirm they exist:
-```
-Created files:
-✓ .clavix/outputs/[project-name]/file-name.md
-✓ .clavix/outputs/[project-name]/another-file.md
-```
-**CHECKPOINT:** Files created successfully.
-```
----
-## Why This Pattern Works
-### ✅ Effective Elements
-1. **Numbered steps** - Clear sequence prevents skipping steps
-2. **Imperative language** - "Use the Write tool" not "You could save"
-3. **Explicit tool names** - "Write tool" not vague "create" or "save"
-4. **Content templates** - Show exactly what goes in each file
-5. **Verification step** - Confirm files exist
-6. **Checkpoint marker** - Enables validation
-### ❌ What Doesn't Work
-1. ~~"Suggest saving to..."~~ - Too passive, agents skip it
-2. ~~"If filesystem access available"~~ - Makes it optional
-3. ~~"Save outputs:"~~ - Doesn't specify HOW
-4. ~~No verification~~ - Can't detect failure
-5. ~~Visual markers only~~ - Agents don't process emoji as semantic content
----
-## Pattern Variations
-### Single File Creation
-```markdown
-**Create Output File (REQUIRED)**
-**Step 1: Create directory**
-```bash
-mkdir -p .clavix/outputs/[project-name]
-```
-**Step 2: Write file**
-Use the Write tool to create `.clavix/outputs/[project-name]/output.md`:
-```markdown
-# [Project Name]
-[Content here]
-```
-**Step 3: Verify file exists**
-Confirm file created: `.clavix/outputs/[project-name]/output.md` ✓
-**CHECKPOINT:** File created successfully.
-```
----
-### Multiple Files with Templates
-```markdown
-**Create Output Files (REQUIRED)**
-You MUST create three files. This is not optional.
-**Step 1: Create directory structure**
-```bash
-mkdir -p .clavix/outputs/[project-name]
-```
-**Step 2: Write mini-prd.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/mini-prd.md`
-Content template:
-```markdown
-# Requirements: [Project Name]
-## Objective
-[Clear goal]
-## Core Requirements
-- [HIGH] Requirement 1
-- [MEDIUM] Requirement 2
-## Technical Constraints
-[Constraints]
-## Success Criteria
-[Criteria]
-```
-**Step 3: Write original-prompt.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/original-prompt.md`
-Content: [Raw extraction in paragraph form]
-**Step 4: Write optimized-prompt.md**
-Use the Write tool to create `.clavix/outputs/[project-name]/optimized-prompt.md`
-Content: [Enhanced version with labeled improvements]
-**Step 5: Verify all files exist**
-List created files:
-```
-✓ .clavix/outputs/[project-name]/mini-prd.md
-✓ .clavix/outputs/[project-name]/original-prompt.md
-✓ .clavix/outputs/[project-name]/optimized-prompt.md
-```
-**CHECKPOINT:** All files created successfully.
-```
----
-### Timestamped Sessions
-```markdown
-**Step 1: Generate session timestamp**
-Create timestamp: `YYYY-MM-DD-HHMM` format (e.g., `2025-11-24-1430`)
-**Step 2: Create session directory**
-```bash
-mkdir -p .clavix/sessions/[timestamp]
-```
-**Step 3: Write session file**
-Use the Write tool to create `.clavix/sessions/[timestamp]/conversation.md`
-[Content here]
-**Step 4: Verify**
-Confirm: `.clavix/sessions/[timestamp]/conversation.md` ✓
-```
----
-## Troubleshooting File Creation
-### Problem: Files Not Created
-**Symptoms:**
-- Agent says "files created" but they don't exist
-- Agent provides content in chat instead of creating files
-- Agent skips file creation step entirely
-**Solution:**
-1. Check instructions use **imperative language**: "You MUST create" not "Suggest saving"
-2. Verify **step-by-step pattern** is present
-3. Ensure **Write tool** is explicitly named
-4. Add **verification step** to detect failure
-5. Make step ordering clear: Create directory → Write files → Verify
-**See:** `.clavix/instructions/troubleshooting/skipped-file-creation.md`
----
-### Problem: Wrong File Paths
-**Symptoms:**
-- Files created in wrong location
-- Missing directory structure
-- Path format inconsistent
-**Solution:**
-1. Always use `mkdir -p` to create parent directories
-2. Show complete path: `.clavix/outputs/[project]/file.md`
-3. Don't use relative paths without context
-4. Verify path format matches project standards
----
-### Problem: Missing Content
-**Symptoms:**
-- Files created but empty
-- Incomplete content
-- Wrong content structure
-**Solution:**
-1. Provide **complete content template** in instructions
-2. Use markdown code blocks to show exact format
-3. Include all required sections
-4. Don't assume agent knows content structure
----
-## Integration Platform Adaptations
-### For Agents with Full File Access (Octofriend, agents.md, Warp)
-Use standard pattern above. No adaptations needed.
----
-### For Agents with Limited File Access (GitHub Copilot)
-Add fallback pattern:
-```markdown
-**Step 2: Write file (with fallback)**
-**Primary approach:** Use the Write tool to create `.clavix/outputs/[project]/file.md`
-**Fallback if Write tool unavailable:**
-If file creation fails, display content and instruct user:
-```
-⚠️ File creation unavailable. Please save this content manually:
-**File path:** `.clavix/outputs/[project]/file.md`
-**Content:**
-```markdown
-[Content here]
-```
-```
-Copy the content above and save to the specified path.
-```
-```
----
-## Examples from Proven Workflows
-### From fast.md (WORKS ✓)
-```markdown
-### Saving the Prompt (REQUIRED)
-After displaying the optimized prompt, you MUST save it to the Clavix system for future reference.
-#### Step 1: Create Directory Structure
-```bash
-mkdir -p .clavix/outputs/prompts/fast
-```
-#### Step 2: Generate Unique Prompt ID
-Create a unique identifier: `fast-YYYYMMDD-HHMM`
-#### Step 3: Save Prompt File
-Use the Write tool to create the prompt file at:
-`.clavix/outputs/prompts/fast/[prompt-id].md`
-[Content template]
-#### Step 5: Verify Saving Succeeded
-Confirm the file path and display to user:
-```
-✓ Prompt saved: .clavix/outputs/prompts/fast/[prompt-id].md
-```
-```
-**Why it works:**
-- Header says "REQUIRED"
-- "you MUST save" (imperative)
-- Numbered steps
-- Explicit Write tool instruction
-- Verification step
----
-### From summarize.md OLD (BROKEN ✗)
-```markdown
-5. Suggest saving to `.clavix/outputs/[session-name]/`
-```
-**Why it failed:**
-- "Suggest" is passive
-- No Write tool instruction
-- No step-by-step breakdown
-- No verification
-- Buried at step 5 (should be step 3-4)
----
-## Summary
-**Always use this pattern for file creation:**
-1. Step 1: mkdir
-2. Step 2-N: Write tool for each file
-3. Step N+1: Verify files exist
-4. Add CHECKPOINT marker
-**Never use:**
-- "Suggest saving"
-- "If available"
-- Vague "create" or "save" without tool name
-- No verification step
-Copy the proven patterns from this document into your workflow instructions.

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

@@ -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