clavix 2.3.1 → 2.4.1

package/dist/templates/slash-commands/droid/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/droid/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

package/dist/templates/slash-commands/droid/prd.md

@@ -1,178 +0,0 @@
----
-name: "Clavix: PRD"
-description: CLEAR-validated PRD generation through Socratic questioning
----
-
-# Clavix PRD Generation - CLEAR Framework Validated
-
-You are helping the user create a Product Requirements Document (PRD) using Clavix's Socratic questioning approach. **Generated PRDs are automatically validated using the CLEAR Framework** (Concise, Logical, Explicit) for AI consumption quality.
-
-## Instructions
-
-1. Guide the user through these strategic questions, **one at a time** with validation:
-
-   **Question 1**: What are we building and why? (Problem + goal in 2-3 sentences)
-
-   - **Validation**: Must have both problem AND goal stated clearly
-   - **If vague/short** (e.g., "a dashboard"): Ask probing questions:
-     - "What specific problem does this dashboard solve?"
-     - "Who will use this and what decisions will they make with it?"
-     - "What happens if this doesn't exist?"
-   - **If "I don't know"**: Ask:
-     - "What triggered the need for this?"
-     - "Can you describe the current pain point or opportunity?"
-   - **Good answer example**: "Sales managers can't quickly identify at-risk deals in our 10K+ deal pipeline. Build a real-time dashboard showing deal health, top performers, and pipeline status so managers can intervene before deals are lost."
-
-   **Question 2**: What are the must-have core features? (List 3-5 critical features)
-
-   - **Validation**: At least 2 concrete features provided
-   - **If vague** (e.g., "user management"): Probe deeper:
-     - "What specific user management capabilities? (registration, roles, permissions, profile management?)"
-     - "Which feature would you build first if you could only build one?"
-   - **If too many** (7+ features): Help prioritize:
-     - "If you had to launch with only 3 features, which would they be?"
-     - "Which features are launch-blockers vs nice-to-have?"
-   - **If "I don't know"**: Ask:
-     - "Walk me through how someone would use this - what would they do first?"
-     - "What's the core value this provides?"
-
-   **Question 3**: Tech stack and requirements? (Technologies, integrations, constraints)
-
-   - **Optional**: Can skip if extending existing project
-   - **If vague** (e.g., "modern stack"): Probe:
-     - "What technologies are already in use that this must integrate with?"
-     - "Any specific frameworks or languages your team prefers?"
-     - "Are there performance requirements (load time, concurrent users)?"
-   - **If "I don't know"**: Suggest common stacks based on project type or skip
-
-   **Question 4**: What is explicitly OUT of scope? (What are we NOT building?)
-
-   - **Validation**: At least 1 explicit exclusion
-   - **Why important**: Prevents scope creep and clarifies boundaries
-   - **If stuck**: Suggest common exclusions:
-     - "Are we building admin dashboards? Mobile apps? API integrations?"
-     - "Are we handling payments? User authentication? Email notifications?"
-   - **If "I don't know"**: Provide project-specific prompts based on previous answers
-
-   **Question 5**: Any additional context or requirements?
-
-   - **Optional**: Press Enter to skip
-   - **Helpful areas**: Compliance needs, accessibility, localization, deadlines, team constraints
-
-2. **Before proceeding to document generation**, verify minimum viable answers:
-   - Q1: Both problem AND goal stated
-   - Q2: At least 2 concrete features
-   - Q4: At least 1 explicit scope exclusion
-   - If missing critical info, ask targeted follow-ups
-
-3. After collecting and validating all answers, generate TWO documents:
-
-   **Full PRD** (comprehensive):
-   ```markdown
-   # Product Requirements Document: [Project Name]
-
-   ## Problem & Goal
-   [User's answer to Q1]
-
-   ## Requirements
-   ### Must-Have Features
-   [User's answer to Q2, expanded with details]
-
-   ### Technical Requirements
-   [User's answer to Q3, detailed]
-
-   ## Out of Scope
-   [User's answer to Q4]
-
-   ## Additional Context
-   [User's answer to Q5 if provided]
-   ```
-
-   **Quick PRD** (2-3 paragraphs, AI-optimized):
-   ```markdown
-   [Concise summary combining problem, goal, and must-have features from Q1+Q2]
-
-   [Technical requirements and constraints from Q3]
-
-   [Out of scope and additional context from Q4+Q5]
-   ```
-
-3. Save both documents to `.clavix/outputs/[project-name]/`
-
-4. **CLEAR Framework Validation** (automatic):
-   - After PRD generation, the quick-prd.md is analyzed using CLEAR framework
-   - Assesses AI consumption quality (Conciseness, Logic, Explicitness)
-   - Displays CLEAR scores and improvement suggestions
-   - Only C, L, E components apply (Adaptive & Reflective not applicable to PRDs)
-
-5. Display file paths, CLEAR validation results, and suggest next steps.
-
-## CLEAR Validation
-
-**What gets validated:**
-- **[C] Concise**: Is the PRD focused and to-the-point for AI agents?
-- **[L] Logical**: Does information flow coherently (context → requirements → constraints)?
-- **[E] Explicit**: Are specifications, formats, and success criteria clear?
-
-**Note:** Adaptive (A) and Reflective (R) components are not applicable to PRDs. For prompt-level CLEAR analysis with all 5 components, use `/clavix:deep` instead.
-
-## Workflow Navigation
-
-**You are here:** PRD Generation (Strategic Planning)
-
-**Common workflows:**
-- **Full PRD workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
-- **From deep mode**: `/clavix:deep` → (strategic scope detected) → `/clavix:prd`
-- **Quick to strategic**: `/clavix:fast` → (realizes complexity) → `/clavix:prd`
-
-**Related commands:**
-- `/clavix:plan` - Generate task breakdown from PRD (next step)
-- `/clavix:implement` - Execute tasks (after plan)
-- `/clavix:summarize` - Alternative: Extract PRD from conversation instead of Q&A
-
-## Tips
-
-- Ask follow-up questions if answers are too vague
-- Help users think through edge cases
-- Keep the process conversational and supportive
-- Generated PRDs are automatically CLEAR-validated for optimal AI consumption
-
-## Troubleshooting
-
-### Issue: User's answers to Q1 are too vague ("make an app")
-**Cause**: User hasn't thought through the problem/goal deeply enough
-**Solution** (inline):
-- Stop and ask probing questions before proceeding
-- "What specific problem does this app solve?"
-- "Who will use this and what pain point does it address?"
-- Don't proceed until both problem AND goal are clear
-
-### Issue: User lists 10+ features in Q2
-**Cause**: Unclear priorities or scope creep
-**Solution** (inline):
-- Help prioritize: "If you could only launch with 3 features, which would they be?"
-- Separate must-have from nice-to-have
-- Document extras in "Additional Context" or "Out of scope"
-
-### Issue: User says "I don't know" to critical questions
-**Cause**: Genuine uncertainty or needs exploration
-**Solution**:
-- For Q1: Ask about what triggered the need, current pain points
-- For Q2: Walk through user journey step-by-step
-- For Q4: Suggest common exclusions based on project type
-- Consider suggesting `/clavix:start` for conversational exploration first
-
-### Issue: CLEAR validation shows low scores after generation
-**Cause**: Answers were too vague or incomplete
-**Solution**:
-- Review the generated PRD
-- Identify specific gaps (missing context, vague requirements)
-- Ask targeted follow-up questions
-- Regenerate PRD with enhanced answers
-
-### Issue: Generated PRD doesn't match user's vision
-**Cause**: Miscommunication during Q&A or assumptions made
-**Solution**:
-- Review each section with user
-- Ask "What's missing or inaccurate?"
-- Update PRD manually or regenerate with corrected answers