clavix 2.3.0 → 2.4.0

package/dist/templates/slash-commands/augment/fast.md

@@ -1,183 +0,0 @@
----
-name: "Clavix: Fast"
-description: CLEAR-guided quick improvements (C, L, E components)
----
-
-# Clavix Fast Mode - CLEAR Framework Quick Improvement
-
-You are helping the user improve their prompt using Clavix's fast mode, which applies the CLEAR Framework (Concise, Logical, Explicit components) with smart triage.
-
-## CLEAR Framework (Fast Mode)
-
-**What is CLEAR?**
-An academically-validated prompt engineering framework by Dr. Leo Lo (University of New Mexico).
-
-**Fast Mode Uses:**
-- **[C] Concise**: Remove verbosity, pleasantries, unnecessary words
-- **[L] Logical**: Ensure coherent sequencing (context → requirements → constraints → output)
-- **[E] Explicit**: Add persona, format, tone, success criteria
-
-**Deep Mode Adds:** [A] Adaptive variations, [R] Reflective validation (use `/clavix:deep` for these)
-
-## Instructions
-
-1. Take the user's prompt: `{{ARGS}}`
-
-2. **CLEAR Analysis** - Assess the prompt using three components:
-
-   - **Conciseness [C]**: Identify verbose language, pleasantries ("please", "could you"), unnecessary qualifiers
-   - **Logic [L]**: Check sequencing and flow - is information presented coherently?
-   - **Explicitness [E]**: Verify specifications - persona, output format, tone, success criteria
-
-3. **CLEAR-Aware Smart Triage**: Use multi-factor content-quality assessment to determine if deep analysis is needed:
-
-   **Primary Indicators** (CLEAR scores - most important):
-   - **Low CLEAR scores**: Conciseness < 60%, Logic < 60%, or Explicitness < 50%
-
-   **Secondary Indicators** (content quality):
-   - **Missing critical elements**: 3+ missing from (context, tech stack, success criteria, user needs, expected output)
-   - **Scope clarity**: Contains vague words ("app", "system", "project", "feature") without defining what/who/why
-   - **Requirement completeness**: Lacks actionable requirements or measurable outcomes
-   - **Context depth**: Extremely brief (<15 words) OR overly verbose (>100 words without structure)
-
-   **Escalation Decision**:
-   - If **Low CLEAR scores** + **2+ Secondary Indicators**: **Strongly recommend `/clavix:deep`**
-   - If **Low CLEAR scores** only: **Suggest `/clavix:deep`** but can proceed with fast mode
-   - Explain which CLEAR component needs deeper analysis and why
-
-   Ask the user:
-   - Switch to deep mode (recommended when strongly recommended)
-   - Continue with fast mode (acceptable for suggestion-level, but at their own risk for strong recommendation)
-
-4. Generate a **CLEAR-optimized** structured prompt with these sections:
-   **Objective**: Clear, specific goal
-   **Requirements**: Detailed, actionable requirements
-   **Technical Constraints**: Technologies, performance needs, integrations
-   **Expected Output**: What the result should look like
-   **Success Criteria**: How to measure completion
-
-5. **CLEAR Changes Made**: List improvements with CLEAR component labels:
-   - **[C]** "Removed 15 unnecessary words and pleasantries"
-   - **[L]** "Restructured: context → requirements → constraints → output"
-   - **[E]** "Added explicit persona (senior developer), output format (React component), tone (production-ready)"
-
-6. Present the CLEAR-optimized prompt in a code block for easy copying.
-
-## Fast Mode Features
-
-**Include (CLEAR C, L, E):**
-- **CLEAR Assessment** (Conciseness, Logic, Explicitness scores with issues)
-- Single CLEAR-optimized improved prompt
-- **CLEAR Changes Made** (labeled with [C], [L], [E] components)
-- Recommendation to use deep mode for Adaptive & Reflective components
-
-**Skip (use `/clavix:deep` instead):**
-- **[A] Adaptive**: Alternative phrasings, structures, flexibility
-- **[R] Reflective**: Validation checklists, edge cases, quality criteria
-- Strategic analysis (architecture, security - that's for `/clavix:prd`)
-
-## Example
-
-If user provides: "Please could you maybe help me create a login page?"
-
-Output:
-```
-## CLEAR Analysis (Fast Mode)
-
-### CLEAR Framework Assessment:
-
-[C] Conciseness: 45%
-    • 4 unnecessary pleasantries detected ("Please", "could you", "maybe", "help me")
-    • Low signal-to-noise ratio (core request is only 4 words)
-
-[L] Logic: 85%
-    • Single request, coherent but minimal
-    • Suggested flow: Context → Requirements → Constraints → Output
-
-[E] Explicitness: 25%
-    • Missing: persona, output format, tone, success criteria, technical constraints
-    • No authentication context specified
-
-Overall CLEAR Score: 51% (needs-improvement)
-
-Recommendation:
-For Adaptive variations (A) and Reflective validation (R), use:
-  clavix deep "<your prompt>"
-
-### CLEAR-Optimized Prompt:
-
-Objective: Build a secure user authentication login page
-
-Requirements:
-- Email and password input fields with validation
-- "Remember me" checkbox
-- "Forgot password" link
-- Clear error messages for invalid credentials
-- Responsive design for mobile and desktop
-
-Technical Constraints:
-- Use React with TypeScript
-- Integrate with existing JWT authentication API
-- Follow WCAG 2.1 AA accessibility standards
-
-Expected Output:
-- Fully functional login component
-- Unit tests with >80% coverage
-
-Success Criteria:
-- Users can log in successfully
-- Invalid credentials show appropriate errors
-- Page is accessible via keyboard navigation
-
-### CLEAR Changes Made:
-
-[C] Removed 4 pleasantries ("Please", "could you", "maybe", "help me"), reduced from 11 words to core intent
-[L] Structured logical flow: Objective → Requirements → Technical Constraints → Expected Output → Success Criteria
-[E] Added explicit specifications: React TypeScript persona, component output format, production-ready tone, accessibility criteria
-```
-
-## Workflow Navigation
-
-**You are here:** Fast Mode (Quick CLEAR Improvement)
-
-**Common workflows:**
-- **Quick cleanup**: `/clavix:fast` → Use improved prompt
-- **Need more depth**: `/clavix:fast` → (suggests) `/clavix:deep` → Comprehensive analysis
-- **Strategic planning**: `/clavix:fast` → (suggests) `/clavix:prd` → Plan → Implement → Archive
-
-**Related commands:**
-- `/clavix:deep` - Full CLEAR analysis (all 5 components: C, L, E, A, R)
-- `/clavix:prd` - Generate PRD for strategic planning
-- `/clavix:start` - Conversational exploration before prompting
-
-## Tips
-
-- **Apply CLEAR framework** systematically: C, L, E components
-- Use **CLEAR-aware triage** to prevent inadequate analysis
-- Label all changes with CLEAR components for education
-- For comprehensive analysis with [A] and [R], recommend `/clavix:deep`
-- For strategic planning, recommend `/clavix:prd`
-- Focus on making prompts **CLEAR** quickly
-
-## Troubleshooting
-
-### Issue: Triage keeps recommending deep mode
-**Cause**: Prompt has low CLEAR scores + multiple secondary indicators
-**Solution**:
-- Accept the recommendation - deep mode will provide better analysis
-- OR improve prompt manually before running fast mode again
-- Check which CLEAR component is scoring low and address it
-
-### Issue: Can't determine if prompt is complex enough for deep mode
-**Cause**: Borderline CLEAR scores or unclear content quality
-**Solution**:
-- Err on side of fast mode first
-- If output feels insufficient, escalate to `/clavix:deep`
-- Use triage as guidance, not absolute rule
-
-### Issue: Improved prompt still feels incomplete
-**Cause**: Fast mode only applies C, L, E components
-**Solution**:
-- Use `/clavix:deep` for Adaptive variations and Reflective validation
-- OR use `/clavix:prd` if strategic planning is needed
-- Fast mode is for quick cleanup, not comprehensive analysis

package/dist/templates/slash-commands/augment/implement.md

@@ -1,267 +0,0 @@
----
-name: "Clavix: Implement"
-description: Execute tasks from the implementation plan
----
-
-# Clavix Implement - AI-Assisted Task Execution
-
-You are helping the user implement tasks from their task plan with AI assistance.
-
-## Instructions
-
-1. **Run the implement command**:
-   ```bash
-   clavix implement
-   ```
-
-   This will:
-   - Show interactive PRD selection (if multiple projects exist)
-   - Locate the `tasks.md` file for the selected/specified project
-   - Show current progress
-   - Display the next incomplete task
-   - Prompt for git auto-commit preferences
-   - Create a config file for the AI agent
-
-   **Note**: You can skip the selection menu by specifying a project:
-   ```bash
-   clavix implement --project my-feature
-   ```
-
-2. **As the AI agent, you should**:
-
-   a. **Read the configuration**:
-      - Load `.clavix-implement-config.json` from the PRD folder
-      - This contains: commit strategy, current task, and progress stats
-
-   b. **Read the PRD for context**:
-      - Open the full PRD to understand requirements
-      - Reference specific sections mentioned in tasks
-
-   c. **Read tasks.md**:
-      - Find the first incomplete task (marked `- [ ]`)
-      - This is your current task to implement
-
-   d. **Implement the task**:
-      - Write/modify code as needed
-      - Follow CLEAR principles
-      - Use PRD requirements as your guide
-      - Ask user for clarification if needed
-
-   e. **Mark task as completed**:
-      - In `tasks.md`, change `- [ ] Task description` to `- [x] Task description`
-      - Update only the specific task you just completed
-
-   f. **Create git commit (if enabled)**:
-      - Check the `commitStrategy` in config
-      - If `per-task`: commit after each task
-      - If `per-5-tasks`: commit after every 5 tasks
-      - If `per-phase`: commit when all tasks in a phase are done
-      - Use descriptive commit messages with task description
-
-   g. **Move to next task**:
-      - Find the next `- [ ]` task in tasks.md
-      - Repeat the process
-
-3. **Session Resume**:
-   - When user runs `clavix implement` again, it automatically picks up from the last incomplete task
-   - No manual tracking needed - the checkboxes in tasks.md are the source of truth
-
-## Git Commit Format
-
-When creating commits, use this format:
-
-```
-clavix: [task description]
-
-Completed tasks:
-- Task 1
-- Task 2
-
-Project: [project-name]
-Generated by Clavix /clavix:implement
-```
-
-## Important Rules
-
-**DO**:
-- Read tasks.md to find the current task
-- Implement ONE task at a time
-- Mark tasks complete by changing `[ ]` to `[x]`
-- Create commits based on the strategy in config
-- Reference the PRD for detailed requirements
-- Ask for clarification when tasks are ambiguous
-
-**DON'T**:
-- Skip tasks or implement out of order
-- Mark tasks complete before actually implementing them
-- Modify multiple tasks' checkboxes at once (only current task)
-- Create commits if strategy is 'none'
-- Assume what code to write - use PRD as source of truth
-
-## Task Blocking Protocol
-
-**When a task is blocked** (cannot be completed), follow this protocol:
-
-### Step 1: Detect Blocking Issues
-
-Common blocking scenarios:
-- **Missing dependencies**: API keys, credentials, external services not available
-- **Unclear requirements**: Task description too vague or conflicts with PRD
-- **External blockers**: Need design assets, content, or third-party integration not ready
-- **Technical blockers**: Required library incompatible, environment issue, access problem
-- **Resource blockers**: Need database, server, or infrastructure not yet set up
-
-### Step 2: Immediate User Communication
-
-**Stop implementation and ask user immediately:**
-```
-"Task blocked: [Task description]
-
-Blocking issue: [Specific blocker, e.g., 'Missing Stripe API key for payment integration']
-
-Options to proceed:
-1. **Provide missing resource** - [What user needs to provide]
-2. **Break into sub-tasks** - I can implement [unblocked parts] now and defer [blocked part]
-3. **Skip for now** - Mark as [BLOCKED], continue with next task, return later
-
-Which option would you like?"
-```
-
-### Step 3: Resolution Strategies
-
-**Option A: User Provides Resource**
-- Wait for user to provide (API key, design, clarification)
-- Once provided, continue with task implementation
-
-**Option B: Create Sub-Tasks** (preferred when possible)
-- Identify what CAN be done without the blocker
-- Break task into unblocked sub-tasks
-- Example: "Implement payment integration" →
-  - [x] Create payment service interface (can do now)
-  - [ ] [BLOCKED: Need Stripe API key] Integrate Stripe SDK
-  - [ ] Add payment UI components (can do now)
-- Implement unblocked sub-tasks, mark blocked ones with [BLOCKED] tag
-
-**Option C: Skip and Mark Blocked**
-- Add [BLOCKED] tag to task in tasks.md: `- [ ] [BLOCKED: Missing API key] Task description`
-- Note the blocker reason
-- Move to next task
-- Return to blocked tasks when unblocked
-
-### Step 4: Track Blocked Tasks
-
-**In tasks.md, use [BLOCKED] notation:**
-```markdown
-## Phase 2: Integration
-- [x] Create API client structure
-- [ ] [BLOCKED: Waiting for API endpoint spec] Implement data sync
-- [ ] Add error handling for API calls
-```
-
-**At end of implement session:**
-- List all blocked tasks
-- Remind user what's needed to unblock each one
-- Suggest next steps
-
-### Common Blocking Scenarios & Resolutions
-
-| Blocker Type | Detection | Resolution |
-|--------------|-----------|------------|
-| Missing API key/credentials | Code requires authentication | Ask user for credentials OR stub with mock for now |
-| Vague requirements | Unclear what to implement | Ask specific questions OR propose implementation for approval |
-| External dependency | Service/API not available | Create interface/mock OR skip and defer |
-| Environment issue | Can't run/test code | Ask user to fix environment OR implement without testing (note risk) |
-| Design/content missing | Need specific assets | Create placeholder OR wait for actual assets |
-
-## Example Workflow
-
-```
-1. User runs: clavix implement
-2. Command shows: "Next task: Implement user authentication"
-3. You (AI agent):
-   - Read PRD authentication requirements
-   - Implement auth logic
-   - Write tests
-   - Update tasks.md: - [x] Implement user authentication
-   - Create git commit (if enabled)
-   - Find next task in tasks.md
-   - Continue or wait for user
-```
-
-## Workflow Navigation
-
-**You are here:** Implement (Task Execution)
-
-**Common workflows:**
-- **Full workflow**: `/clavix:plan` → `/clavix:implement` → [execute all tasks] → `/clavix:archive`
-- **Resume work**: `/clavix:implement` → Continue from last incomplete task
-- **Iterative**: `/clavix:implement` → [complete task] → [pause] → `/clavix:implement` → [continue]
-
-**Related commands:**
-- `/clavix:plan` - Generate/regenerate task breakdown (previous step)
-- `/clavix:archive` - Archive completed project (final step)
-- `/clavix:prd` - Review PRD for context during implementation
-
-## Tips
-
-- The implementation is meant to be iterative and collaborative
-- User can pause/resume at any time
-- Tasks are designed to be atomic and independently implementable
-- Use the PRD as the authoritative source for "what to build"
-- Use tasks.md as the guide for "in what order"
-
-## Troubleshooting
-
-### Issue: `.clavix-implement-config.json` not found
-**Cause**: User hasn't run `clavix implement` CLI command first
-**Solution** (inline):
-- Error: "Config file not found. Run `clavix implement` first to initialize"
-- CLI creates config and shows first task
-- AI agent should wait for config before proceeding
-
-### Issue: Cannot find next incomplete task in tasks.md
-**Cause**: All tasks completed OR tasks.md corrupted
-**Solution**:
-- Check if all tasks are `[x]` - if yes, congratulate completion!
-- Suggest `/clavix:archive` for completed project
-- If tasks.md corrupted, ask user to review/regenerate
-
-### Issue: Task description unclear or conflicts with PRD
-**Cause**: Task breakdown was too vague or PRD changed
-**Solution** (inline - covered by Task Blocking Protocol):
-- Stop and ask user for clarification
-- Reference PRD section if mentioned
-- Propose interpretation for user approval
-- Update task description in tasks.md after clarification
-
-### Issue: Git commit fails (wrong strategy, hook error, etc.)
-**Cause**: Git configuration issue or commit hook failure
-**Solution**:
-- Show error to user
-- Suggest checking git status manually
-- Ask if should continue without commit or fix issue first
-- Note: Commits are convenience, not blocker - can proceed without
-
-### Issue: Multiple [BLOCKED] tasks accumulating
-**Cause**: Dependencies or blockers not being resolved
-**Solution**:
-- After 3+ blocked tasks, pause and report to user
-- List all blockers and what's needed to resolve
-- Ask user to prioritize: unblock tasks OR continue with unblocked ones
-- Consider if project should be paused until blockers cleared
-
-### Issue: Task completed but tests failing
-**Cause**: Implementation doesn't meet requirements
-**Solution**:
-- Do NOT mark task as complete if tests fail
-- Fix failing tests before marking [x]
-- If tests are incorrectly written, fix tests first
-- Task isn't done until tests pass
-
-### Issue: Implementing in wrong order (skipped dependencies)
-**Cause**: AI agent or user jumped ahead
-**Solution**:
-- Stop and review tasks.md order
-- Check if skipped task was a dependency
-- Implement missed dependency first
-- Follow sequential order unless explicitly instructed otherwise

package/dist/templates/slash-commands/augment/plan.md

@@ -1,173 +0,0 @@
----
-name: "Clavix: Plan"
-description: Generate implementation task breakdown from PRD
----
-
-# Clavix Plan - Task Breakdown Generator
-
-You are helping the user generate a CLEAR-optimized implementation task breakdown from their PRD.
-
-## Instructions
-
-### Part A: Procedural Steps (CLI Commands)
-
-1. **Locate the PRD outputs**:
-   - Look for the most recent artifacts in `.clavix/outputs/[project-name]/`
-   - Accepted sources: `full-prd.md`, `quick-prd.md`, `mini-prd.md`, or `optimized-prompt.md`
-   - **If not found**: Error inline - "No PRD found in `.clavix/outputs/`. Use `/clavix:prd` or `/clavix:summarize` first."
-
-2. **Run the plan command**:
-   ```bash
-   clavix plan
-   ```
-
-   Or specify a project:
-   ```bash
-   clavix plan --project project-name
-   ```
-
-   Or generate tasks directly from a saved session (auto-creates mini-prd.md):
-   ```bash
-   clavix plan --session SESSION_ID
-   ```
-
-   The CLI will prompt you to pick a project when multiple outputs are available.
-
-### Part B: Behavioral Guidance (Task Breakdown Strategy)
-
-3. **How to structure tasks** (CLEAR-optimized task breakdown):
-
-   **Task Granularity Principles:**
-   - **[C] Concise**: Each task = 1 clear action (not "Build authentication system", but "Create user registration endpoint")
-   - **[L] Logical**: Tasks flow in implementation order (database schema → backend logic → frontend UI)
-   - **[E] Explicit**: Tasks specify deliverable (not "Add tests", but "Write unit tests for user service with >80% coverage")
-
-   **Atomic Task Guidelines:**
-   - **Ideal size**: Completable in 15-60 minutes
-   - **Too large**: "Implement user authentication" → Break into registration, login, logout, password reset
-   - **Too small**: "Import React" → Combine with "Setup component structure"
-   - **Dependencies**: If Task B needs Task A, ensure A comes first
-
-   **Phase Organization:**
-   - Group related tasks into phases (Setup, Core Features, Testing, Polish)
-   - Each phase should be independently deployable when possible
-   - Critical path first (must-haves before nice-to-haves)
-
-4. **Review and customize generated tasks**:
-   - The command will generate `tasks.md` in the PRD folder
-   - Tasks are organized into logical phases with CLEAR principles
-   - Each task includes:
-     - Checkbox `- [ ]` for tracking
-     - Clear deliverable description
-     - Optional reference to PRD section `(ref: PRD Section)`
-   - **You can edit tasks.md** before implementing:
-     - Add/remove tasks
-     - Adjust granularity
-     - Reorder for better flow
-     - Add notes or sub-tasks
-
-5. **CLEAR Task Labeling** (optional, for education):
-   When reviewing tasks, you can annotate improvements:
-   - **[C]**: "Split vague 'Add UI' into 3 concrete tasks"
-   - **[L]**: "Reordered tasks: database schema before API endpoints"
-   - **[E]**: "Added specific acceptance criteria (>80% test coverage)"
-
-6. **Next steps**:
-   - Review and edit `tasks.md` if needed
-   - Then run `/clavix:implement` to start implementation
-
-## Task Format
-
-The generated `tasks.md` will look like:
-
-```markdown
-# Implementation Tasks
-
-**Project**: [Project Name]
-**Generated**: [Timestamp]
-
----
-
-## Phase 1: Feature Name
-- [ ] Task 1 description (ref: PRD Section)
-- [ ] Task 2 description
-- [ ] Task 3 description
-
-## Phase 2: Another Feature
-- [ ] Task 4 description
-- [ ] Task 5 description
-
----
-
-*Generated by Clavix /clavix:plan*
-```
-
-## Workflow Navigation
-
-**You are here:** Plan (Task Breakdown)
-
-**Common workflows:**
-- **PRD workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
-- **Conversation workflow**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
-- **Standalone**: [Existing PRD] → `/clavix:plan` → Review tasks.md → `/clavix:implement`
-
-**Related commands:**
-- `/clavix:prd` - Generate PRD (typical previous step)
-- `/clavix:summarize` - Extract mini-PRD from conversation (alternative previous step)
-- `/clavix:implement` - Execute generated tasks (next step)
-
-## Tips
-
-- Tasks are automatically optimized using CLEAR framework
-- Each task is concise and actionable
-- Tasks can reference specific PRD sections
-- Supports mini-PRD outputs from `/clavix:summarize` and session workflows via `--session` or `--active-session`
-- You can manually edit tasks.md before implementing
-- Use `--overwrite` flag to regenerate if needed
-
-## Troubleshooting
-
-### Issue: No PRD found in `.clavix/outputs/`
-**Cause**: User hasn't generated a PRD yet
-**Solution** (inline - already in template):
-- Show error: "No PRD found in `.clavix/outputs/`"
-- Suggest: "Use `/clavix:prd` or `/clavix:summarize` to generate one first"
-- Do not proceed with plan generation
-
-### Issue: Generated tasks are too granular (100+ tasks)
-**Cause**: Over-decomposition or large project scope
-**Solution**:
-- Group related micro-tasks into larger atomic tasks
-- Each task should be 15-60 minutes, not 5 minutes
-- Combine setup/configuration tasks
-- Suggest breaking project into multiple PRDs if truly massive
-
-### Issue: Generated tasks are too high-level (only 3-4 tasks)
-**Cause**: PRD was too vague or task breakdown too coarse
-**Solution**:
-- Review PRD - if vague, regenerate with more detail
-- Break each high-level task into 3-5 concrete sub-tasks
-- Each task should have a clear, testable deliverable
-
-### Issue: Tasks don't follow logical dependency order
-**Cause**: Generator didn't detect dependencies correctly
-**Solution**:
-- Manually reorder in tasks.md (database before API, API before UI)
-- Follow CLEAR [L] Logic principle: ensure sequential coherence
-- Group by technical layers or feature completion
-
-### Issue: Tasks conflict with PRD or duplicate work
-**Cause**: Misinterpretation of PRD or redundant task generation
-**Solution**:
-- Review PRD and tasks side-by-side
-- Remove duplicate tasks
-- Align tasks with PRD requirements
-- Use `--overwrite` to regenerate after PRD clarification
-
-### Issue: `tasks.md` already exists, unsure if should regenerate
-**Cause**: Previous plan exists for this PRD
-**Solution**:
-- Check if tasks.md has progress (any [x] checkboxes)
-- If no progress: Safe to use `--overwrite`
-- If progress exists: Review carefully before overwriting
-- Consider manual edits instead of full regeneration