clavix 4.2.0 → 4.3.2

package/dist/templates/instructions/core 2/clavix-mode.md

@@ -1,275 +0,0 @@
-# Understanding Clavix Modes
-
-## Two Types of Clavix Workflows
-
-Clavix has **two distinct modes** based on the command type:
-
-### CLAVIX PLANNING MODE (Requirements & Documentation)
-
-**Commands:** `/clavix:start`, `/clavix:summarize`, `/clavix:fast`, `/clavix:deep`, `/clavix:prd`
-
-**Your role:**
-- Ask questions about requirements
-- Create PRDs (Product Requirements Documents)
-- Generate optimized prompts
-- Extract and structure requirements
-- Analyze and improve prompt quality
-- Document features, constraints, success criteria
-
-**DO NOT implement features during these workflows.**
-
-### CLAVIX IMPLEMENTATION MODE (Code Execution)
-
-**Commands:** `/clavix:implement`, `/clavix:execute`, `/clavix:task-complete`
-
-**Your role:**
-- Write code and implement features
-- Execute tasks from tasks.md
-- Complete implementation work
-- Mark tasks as completed
-
-**DO implement code during these workflows.**
-
----
-
-## Core Principle
-
-**Know which mode you're in based on the command:**
-
-| Command | Mode | Implement? |
-|---------|------|------------|
-| `/clavix:start` | Planning | ✗ NO |
-| `/clavix:summarize` | Planning | ✗ NO |
-| `/clavix:fast` | Planning | ✗ NO |
-| `/clavix:deep` | Planning | ✗ NO |
-| `/clavix:prd` | Planning | ✗ NO |
-| `/clavix:plan` | Planning (Pre-Implementation) | ✗ NO |
-| `/clavix:implement` | Implementation | ✓ YES |
-| `/clavix:execute` | Implementation | ✓ YES |
-| `/clavix:task-complete` | Implementation | ✓ YES |
-
----
-
-## What You Should Do
-
-✓ **Ask questions** about what the user wants to build
-✓ **Generate PRDs** that describe the requirements
-✓ **Create optimized prompts** that can be used for implementation later
-✓ **Extract and structure requirements** from conversations
-✓ **Analyze and improve** prompt quality
-✓ **Document** features, constraints, and success criteria
-
----
-
-## What You Should NOT Do
-
-**DO NOT IMPLEMENT. DO NOT IMPLEMENT. DO NOT IMPLEMENT.**
-
-✗ **DO NOT write application code** for the feature being discussed
-✗ **DO NOT implement** the feature or component
-✗ **DO NOT generate** functions, classes, or modules for the actual application
-✗ **DO NOT start building** the feature itself
-✗ **DO NOT create example implementations** unless explicitly asked
-
----
-
-## Standard Workflow: PRD → Plan → Implement → Archive
-
-**The typical Clavix workflow:**
-
-1. **Planning Phase** (`/clavix:prd`)
-   - Creates PRD (full + quick versions)
-   - Mode: PLANNING
-   - Output: `.clavix/outputs/{project}/full-prd.md` + `quick-prd.md`
-
-2. **Task Preparation** (`/clavix:plan`)
-   - Transforms PRD into curated tasks.md
-   - Mode: PLANNING (Pre-Implementation)
-   - Output: `.clavix/outputs/{project}/tasks.md`
-
-3. **Implementation Phase** (`/clavix:implement`)
-   - Agent executes tasks systematically
-   - Mode: IMPLEMENTATION
-   - Uses `task-complete` to mark progress
-
-4. **Completion** (`/clavix:archive`)
-   - Archives completed project
-   - Mode: Management
-
-**Key principle:** Planning workflows create documents. Implementation workflows write code.
-
----
-
-## When to Switch Modes
-
-**User says:** "Now implement this" or "Build this feature"
-→ **Switch to IMPLEMENTATION MODE** if not already in implementation command
-
-**User runs:** `/clavix:implement` or `/clavix:execute`
-→ **You are in IMPLEMENTATION MODE** - write code
-
-**User runs:** `/clavix:prd` or `/clavix:fast` or `/clavix:start`
-→ **You are in PLANNING MODE** - gather requirements, don't implement
-
----
-
-## When Unsure
-
-If you're not sure whether the user wants planning or implementation, **ASK:**
-
-> "Should I implement this feature now, or continue with requirements and planning?"
-
----
-
-## Common Mistakes to Avoid
-
-### ❌ Wrong: Jumping to Implementation
-
-**User:** "I want to build a todo app with authentication"
-
-**Wrong response:**
-```typescript
-// Creating TodoApp component
-export function TodoApp() {
-  const [todos, setTodos] = useState([]);
-  // ... implementation
-}
-```
-
-### ✓ Right: Gathering Requirements
-
-**User:** "I want to build a todo app with authentication"
-
-**Right response:**
-> "Let me help you plan this todo app. A few clarifying questions:
->
-> 1. What authentication method do you want? (OAuth, email/password, magic link?)
-> 2. Should todos be per-user or shared across teams?
-> 3. What todo features are essential? (priority levels, due dates, categories?)
-> 4. Any specific technical constraints or framework preferences?
->
-> Once we've gathered all requirements, I'll create a comprehensive PRD and optimized prompt for implementation."
-
----
-
-## Mode Detection Examples
-
-### Scenario 1: User Starts Conversational Mode
-
-**Command:** `/clavix:start`
-
-**Your mode:** CLAVIX PLANNING MODE
-
-**Actions:**
-- Enter conversational mode
-- Ask clarifying questions
-- Track requirements
-- DO NOT implement anything
-- Remind user to use `/clavix:summarize` when ready
-
----
-
-### Scenario 2: User Asks for Summarization
-
-**Command:** `/clavix:summarize`
-
-**Your mode:** CLAVIX PLANNING MODE
-
-**Actions:**
-- Analyze conversation
-- Extract requirements
-- Create mini-PRD
-- Create optimized prompts
-- Save files
-- DO NOT implement the feature
-
----
-
-### Scenario 3: User Runs Implement Command
-
-**Command:** `/clavix:implement`
-
-**Your mode:** CLAVIX IMPLEMENTATION MODE
-
-**Actions:**
-- Read tasks.md from `.clavix/outputs/{project}/`
-- Execute tasks systematically
-- Write actual implementation code
-- Use `/clavix:task-complete` to mark tasks done
-- Continue until all tasks completed
-
----
-
-### Scenario 4: User Runs Execute Command
-
-**Command:** `/clavix:execute` or `/clavix:execute --latest`
-
-**Your mode:** CLAVIX IMPLEMENTATION MODE
-
-**Actions:**
-- Load saved prompt from fast/deep workflow
-- Implement the feature described in the prompt
-- Write actual code
-- Complete the implementation
-
----
-
-### Scenario 5: Ambiguous Request During Planning
-
-**User:** "What do you think about adding real-time updates?"
-
-**Context:** Currently in conversational mode (`/clavix:start`)
-
-**Your mode:** CLAVIX PLANNING MODE (clarify first)
-
-**Response:**
-> "Are you asking me to:
-> 1. Discuss the requirements for real-time updates and add them to our planning? (I'll stay in planning mode)
-> 2. Implement real-time updates now? (You'd need to run `/clavix:implement` for that)
->
-> Since we're in planning mode, I'll assume option 1 unless you explicitly request implementation."
-
----
-
-### Scenario 6: User Gives Direct Implementation Request
-
-**User:** "Now implement this feature" or "Build the dashboard we discussed"
-
-**Your mode:** Check context first
-
-**If no `/clavix:implement` command was run:**
-- Suggest: "To implement this, please run `/clavix:implement` or `/clavix:execute`. This ensures proper task tracking and file management."
-
-**If `/clavix:implement` command was run:**
-- You're already in CLAVIX IMPLEMENTATION MODE
-- Proceed with implementation
-
----
-
-## Self-Correction
-
-If you catch yourself implementing during a Clavix workflow:
-
-1. **STOP immediately**
-2. **Delete** the implementation attempt
-3. **Apologize**: "I apologize - I was jumping to implementation. Let me continue with requirements gathering instead."
-4. **Return** to asking questions or documenting requirements
-5. **Reference** this file for clarification
-
----
-
-## Summary
-
-**Two distinct Clavix modes:**
-
-1. **CLAVIX PLANNING MODE** (`start`, `summarize`, `fast`, `deep`, `prd`, `plan`)
-   - Create PRDs, prompts, documentation
-   - DO NOT implement features
-
-2. **CLAVIX IMPLEMENTATION MODE** (`implement`, `execute`, `task-complete`)
-   - Write code and build features
-   - DO implement what's been planned
-
-**Standard workflow:** PRD → Plan → Implement → Archive
-
-**When in doubt:** Check which command was run, or ask the user to clarify.

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

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