clavix 4.2.0 → 4.3.1

package/dist/templates/instructions/README 2.md

@@ -1,311 +0,0 @@
-# Clavix Instructions Hierarchy
-
-This directory contains the complete instruction set for AI agents consuming Clavix workflows. Understanding this hierarchy is critical for maintaining consistent, high-quality agent behavior.
-
----
-
-## 📐 Documentation Architecture
-
-```
-Canonical Templates (SOURCE OF TRUTH)
-  src/templates/slash-commands/_canonical/
-  ├── fast.md, deep.md, prd.md
-  ├── start.md, summarize.md
-  ├── plan.md, implement.md, execute.md
-  └── archive.md, prompts.md
-    ↓ (copied during clavix init)
-Instruction Files (AUTO-GENERATED)
-  .clavix/instructions/
-  ├── workflows/         - Complete workflows (COPIED from canonical)
-  ├── core/             - Foundational concepts (static)
-  └── troubleshooting/  - Common issues (static)
-    ↓ (reference)
-Generic Connectors (THIN WRAPPERS)
-  src/templates/agents/
-  ├── agents.md          - Generic agents
-  ├── octo.md           - Octofriend-specific
-  ├── copilot-instructions.md - GitHub Copilot
-  └── warp.md           - Warp AI
-```
-
----
-
-## 🎯 Core Principles
-
-### 1. Single Source of Truth
-
-**Canonical templates** (`src/templates/slash-commands/_canonical/`) are the definitive reference:
-- Complete workflow descriptions
-- Official command behavior
-- Authoritative patterns and examples
-- NEVER modified for size/brevity - they define the standard
-
-**Rule:** When canonical and instruction files conflict, canonical wins.
-
-### 2. Agent-Optimized Instructions
-
-**Instruction files** (`src/templates/instructions/`) are derived from canonical templates but optimized for AI agent consumption:
-- Must match canonical workflows 100% in substance
-- Can reorganize for better agent comprehension
-- Add explicit checkpoints, self-correction checks, troubleshooting
-- Include "Common Mistakes" sections with wrong/right examples
-- Expand on ambiguous points from canonical
-
-**Rule:** Instruction files implement canonical, never contradict it.
-
-### 3. Thin Generic Connectors
-
-**Generic connector files** (`src/templates/agents/`) are minimal wrappers:
-- Reference instruction files, don't duplicate them
-- Platform-specific guidance ONLY (model switching, tool limitations, etc.)
-- Brief workflow overview + standard workflow (PRD → Plan → Implement → Archive)
-- Command quick reference table
-- Common mistakes specific to platform
-
-**Target sizes:**
-- agents.md: 4-7K (generic, no platform features)
-- octo.md: 7-10K (Octofriend has unique features)
-- copilot-instructions.md: 5-7K (GitHub Copilot integration)
-- warp.md: 5-7K (Warp AI-specific)
-
-**Rule:** If it's in an instruction file, don't duplicate it in a connector file.
-
----
-
-## 📂 Directory Structure
-
-### `/workflows/` - Step-by-Step Workflows
-
-Complete, executable workflows with explicit steps:
-
-| File | Purpose | Key Sections |
-|------|---------|--------------|
-| `start.md` | Conversational mode entry | Questions, complexity tracking, mode transitions |
-| `summarize.md` | Extract requirements from conversation | Pre-validation, extraction, file creation, optimization |
-| `fast.md` | Quick prompt optimization | Intent detection, quality assessment, smart triage |
-| `deep.md` | Comprehensive analysis | Strategic scope, alternatives, validation, edge cases, risks |
-| `prd.md` | PRD generation via Socratic questions | 5-question sequence, validation criteria, file-saving protocol |
-
-**Pattern:** Each workflow file includes:
-- CLAVIX PLANNING MODE block (clarifies planning vs implementation)
-- Complete workflow steps with checkpoints
-- Self-correction checks
-- Common mistakes (wrong/right examples)
-- Troubleshooting references
-- Integration with other workflows
-
-### `/core/` - Foundational Concepts
-
-Cross-workflow patterns and principles:
-
-| File | Purpose | Key Content |
-|------|---------|-------------|
-| `clavix-mode.md` | Planning vs implementation distinction | Mode table, standard workflow, command categorization |
-| `file-operations.md` | File creation patterns | Write tool usage, verification steps, error handling |
-| `verification.md` | Checkpoint patterns | Self-correction triggers, validation approaches |
-
-**Purpose:** Define concepts used across multiple workflows to avoid duplication.
-
-### `/troubleshooting/` - Common Issues
-
-Problem → Solution guides:
-
-| File | Purpose | Symptoms & Solutions |
-|------|---------|---------------------|
-| `jumped-to-implementation.md` | Agent implemented during planning | Detect, stop, apologize, return to planning |
-| `skipped-file-creation.md` | Files not created | Explicit Write tool steps, verification protocol |
-| `mode-confusion.md` | Unclear planning vs implementation | Ask user to clarify, explain mode boundaries |
-
-**Pattern:** Each troubleshooting file includes:
-- Symptoms (how to detect the problem)
-- Root cause (why it happened)
-- Solution (step-by-step fix)
-- Prevention (how to avoid in future)
-
----
-
-## 🔄 Maintenance Workflow
-
-### When Adding New Workflow
-
-1. **Create canonical template** in `src/templates/slash-commands/_canonical/`
-   - Complete workflow description
-   - All steps, examples, edge cases
-   - This is the official reference
-
-2. **NO NEED to create instruction file** - It's auto-copied during init
-   - During `clavix init`, canonical templates are automatically copied to `.clavix/instructions/workflows/`
-   - User projects get fresh copy on init/update
-   - **Single source of truth:** Only maintain canonical template
-
-3. **Update generic connectors** in `src/templates/agents/` (if needed)
-   - Add table reference to new workflow
-   - Update workflow detection keywords
-   - DO NOT duplicate workflow steps
-
-4. **Update this README** if new pattern/principle introduced
-
-### When Modifying Existing Workflow
-
-1. **Update canonical template** - This is source of truth
-2. **Users run `clavix update`** - Refreshes `.clavix/instructions/workflows/` from canonical
-3. **Test:** Verify `clavix update` propagates changes correctly
-4. **No manual duplication needed** - InstructionsGenerator copies from canonical automatically
-
-### When Reporting Verbosity Issues
-
-**Bloat checklist:**
-1. Is canonical template duplicated in instruction file? → Remove from instruction, reference canonical
-2. Is instruction file duplicated in connector file? → Remove from connector, reference instruction
-3. Is workflow description inline in connector? → Remove, add table reference to instruction file
-4. Are "Common Mistakes" duplicated across files? → Keep in instruction file only
-5. Is command reference table too detailed? → Condense to single-line purpose
-
-**Size targets:**
-- Canonical templates: 10-20K (complete reference, no size limit)
-- Instruction files: 10-18K (agent-optimized, comprehensive)
-- Generic connectors: 4-10K (thin wrappers)
-
----
-
-## 🧠 Design Philosophy
-
-### Why Three Layers?
-
-**Layer 1: Canonical Templates**
-- **Audience:** CLI implementation, human developers, official documentation
-- **Purpose:** Define authoritative behavior
-- **Constraint:** Complete and accurate, no brevity requirement
-
-**Layer 2: Instruction Files**
-- **Audience:** AI agents (all platforms)
-- **Purpose:** Executable guidance with self-correction
-- **Constraint:** Must match canonical, optimized for agent comprehension
-
-**Layer 3: Generic Connectors**
-- **Audience:** Platform-specific agents (Copilot, Octofriend, Warp, generic)
-- **Purpose:** Minimal platform-specific wrapper + references
-- **Constraint:** Keep thin, reference instruction files, platform-unique guidance only
-
-### Why Not Just One File?
-
-**Problems with single-file approach:**
-1. **Duplication:** Same workflow described 4+ times (canonical + 3 platforms)
-2. **Maintenance burden:** Update one workflow = edit 4+ files
-3. **Size bloat:** Each platform file becomes 15-20K
-4. **Inconsistency:** Descriptions drift apart over time
-5. **Confusion:** Agent sees multiple versions, unclear which is authoritative
-
-**Benefits of three-layer hierarchy:**
-1. **DRY principle:** Write workflow once (instruction file), reference everywhere
-2. **Single source of truth:** Canonical → Instruction → Connector flow
-3. **Platform focus:** Connector files focus on platform-specific value (model switching, tool limitations)
-4. **Maintainability:** Fix bug in one instruction file, all platforms benefit
-5. **Clarity:** Agent knows where to look - instruction file for workflow, connector for platform quirks
-
----
-
-## 📋 Quick Reference Tables
-
-### Standard Workflow
-
-All workflows follow this progression:
-
-```
-PRD Creation → Task Planning → Implementation → Archive
-```
-
-| Phase | Command | Output | Mode |
-|-------|---------|--------|------|
-| **Planning** | `clavix prd` or conversational | `full-prd.md` + `quick-prd.md` | PLANNING |
-| **Task Prep** | `clavix plan` | `tasks.md` | PLANNING (Pre-Implementation) |
-| **Implementation** | `clavix implement` | Executed code | IMPLEMENTATION |
-| **Completion** | `clavix archive` | Archived project | Management |
-
-### Mode Distinction
-
-| 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 |
-
-### File Size Expectations
-
-| File Type | Size Range | Line Range | Purpose |
-|-----------|-----------|------------|---------|
-| Canonical Template | 10-20K | 300-600 lines | Complete reference (no limit) |
-| Instruction File | 10-18K | 350-650 lines | Agent-executable workflows |
-| Generic Connector | 4-10K | 150-300 lines | Thin wrapper + platform-specific |
-
----
-
-## 🔧 Troubleshooting
-
-### "Agent jumped to implementation during planning"
-
-**Root cause:** Agent didn't recognize planning mode boundary
-
-**Fix:**
-1. Check instruction file has CLAVIX PLANNING MODE block at top
-2. Verify "DO NOT IMPLEMENT" warnings present and clear
-3. Add self-correction check: "Check 1: Am I Implementing?"
-4. Reference `troubleshooting/jumped-to-implementation.md`
-
-### "Agent skipped file creation"
-
-**Root cause:** File-saving protocol not explicit enough
-
-**Fix:**
-1. Add explicit step-by-step file creation section
-2. Include "Step N: Verify Files Were Created" with ls command
-3. Add common mistake: "Skipping file creation"
-4. Reference `troubleshooting/skipped-file-creation.md`
-
-### "Generic connector file too large (>10K)"
-
-**Root cause:** Duplicating instruction file content
-
-**Fix:**
-1. Identify duplicated workflow descriptions
-2. Replace with table reference to instruction file
-3. Keep only platform-specific guidance (model switching, tool limitations, etc.)
-4. Condense CLI reference table (one line per command)
-5. Remove detailed workflow explanations (link to instruction file instead)
-
-### "Instruction file doesn't match canonical"
-
-**Root cause:** Manual edit to instruction file without checking canonical
-
-**Fix:**
-1. Read canonical template: `src/templates/slash-commands/_canonical/<workflow>.md`
-2. Compare with instruction file: `src/templates/instructions/workflows/<workflow>.md`
-3. Ensure substance matches 100%
-4. Reorganization for agent clarity is OK, contradicting canonical is NOT
-
----
-
-## 📚 Additional Resources
-
-**Related documentation:**
-- `src/templates/slash-commands/_canonical/README.md` - Canonical template guidelines
-- `src/templates/agents/README.md` - Generic connector patterns (if exists)
-- `CONTRIBUTING.md` - General contribution guidelines
-- `ARCHITECTURE.md` - Overall Clavix architecture
-
-**Key files to read first:**
-- `core/clavix-mode.md` - Understand planning vs implementation
-- `workflows/fast.md` - See complete workflow pattern
-- `../agents/octo.md` - See thin connector example (post-v3.6.1)
-
----
-
-**Last updated:** v3.6.1 (November 2025)
-
-**Maintainers:** Ensure this README stays synchronized with actual instruction hierarchy.

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.