clavix 2.1.2 → 2.2.0

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

@@ -9,9 +9,12 @@ You are helping the user generate a CLEAR-optimized implementation task breakdow
 
 ## 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
@@ -30,15 +33,47 @@ You are helping the user generate a CLEAR-optimized implementation task breakdow
 
    The CLI will prompt you to pick a project when multiple outputs are available.
 
-3. **Review the generated tasks**:
-   - The command will generate `tasks.md` in the PRD folder
-   - Tasks are organized into logical phases
-   - Each task follows CLEAR framework principles
-   - Tasks include checkboxes `- [ ]` for tracking completion
+### 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. **Next steps**:
+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
-   - Add, remove, or modify tasks as appropriate
    - Then run `/clavix:implement` to start implementation
 
 ## Task Format
@@ -67,6 +102,20 @@ The generated `tasks.md` will look like:
 *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
@@ -75,3 +124,50 @@ The generated `tasks.md` will look like:
 - 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/roocode/prd.md

@@ -9,19 +9,63 @@ You are helping the user create a Product Requirements Document (PRD) using Clav
 
 ## Instructions
 
-1. Guide the user through these strategic questions, one at a time:
-
-   **Question 1**: 🎯 What are we building and why? (Problem + goal in 2-3 sentences)
-
-   **Question 2**: ⚡ What are the must-have core features? (List 3-5 critical features)
-
-   **Question 3**: 🔧 Tech stack and requirements? (Technologies, integrations, constraints - press Enter to skip if extending existing project)
-
-   **Question 4**: 🚫 What is explicitly OUT of scope? (What are we NOT building?)
-
-   **Question 5**: 💡 Any additional context or requirements? (Optional - press Enter to skip)
-
-2. After collecting all answers, generate TWO documents:
+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
@@ -72,9 +116,63 @@ You are helping the user create a Product Requirements Document (PRD) using Clav
 
 **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

package/dist/templates/slash-commands/roocode/start.md

@@ -24,7 +24,9 @@ You are starting a Clavix conversational session for iterative prompt and requir
    - Help them think through user needs
    - Identify potential challenges
 
-3. Keep track of key points discussed:
+3. **Track conversation topics and manage complexity**:
+
+   **Key points to track:**
    - Problem statement
    - Target users
    - Core features
@@ -32,6 +34,27 @@ You are starting a Clavix conversational session for iterative prompt and requir
    - Success criteria
    - Constraints and scope
 
+   **Multi-topic detection** (track distinct topics being discussed):
+   - Consider topics distinct if they address different problems/features/user needs
+   - Examples: "dashboard for sales" + "API for integrations" + "mobile app" = 3 topics
+
+   **When 3+ distinct topics detected**:
+   Auto-suggest focusing: "I notice we're discussing multiple distinct areas: [Topic A: summary], [Topic B: summary], and [Topic C: summary]. To ensure we develop clear requirements for each, would you like to:
+   - **Focus on one** - Pick the most important topic to explore thoroughly first
+   - **Continue multi-topic** - We'll track all of them, but the resulting prompt may need refinement
+   - **Create separate sessions** - Start fresh for each topic with dedicated focus"
+
+   **Complexity indicators** (suggest wrapping up/summarizing):
+   - Conversation > 15 exchanges
+   - Requirements for 5+ major features discussed
+   - Multiple technology stacks mentioned
+   - Significant scope changes or pivots occurred
+
+   When complexity threshold reached: "We've covered substantial ground. Would you like to:
+   - Continue exploring
+   - Use `/clavix:summarize` to extract what we have so far
+   - Switch to `/clavix:prd` for more structured planning"
+
 4. Be conversational and supportive:
    - Don't interrogate - have a natural discussion
    - Build on their ideas
@@ -61,6 +84,59 @@ After the conversational session, `/clavix:summarize` will:
 
 [Continue conversational refinement...]
 
+## Workflow Navigation
+
+**You are here:** Conversational Mode (Iterative Exploration)
+
+**Common workflows:**
+- **Exploration to prompt**: `/clavix:start` → [conversation] → `/clavix:summarize` → CLEAR-optimized prompt
+- **Exploration to PRD**: `/clavix:start` → [conversation] → `/clavix:prd` (answer questions with discussed info)
+- **Exploration to planning**: `/clavix:start` → `/clavix:summarize` → `/clavix:plan` → Implement
+
+**Related commands:**
+- `/clavix:summarize` - Extract and CLEAR-optimize conversation (typical next step)
+- `/clavix:prd` - Switch to structured PRD generation
+- `/clavix:fast` or `/clavix:deep` - Direct prompt improvement instead of conversation
+
 ## Note
 
 The goal is natural exploration of requirements, not a rigid questionnaire. Follow the user's lead while gently guiding toward clarity.
+
+## Troubleshooting
+
+### Issue: Conversation going in circles without progress
+**Cause**: Unclear focus or too many topics being explored
+**Solution** (inline):
+- Pause and summarize: "So far we've discussed [A], [B], [C]. Which should we focus on?"
+- Suggest focusing on one topic at a time
+- Or suggest `/clavix:summarize` to extract what's been discussed
+
+### Issue: User provides very high-level descriptions ("build something cool")
+**Cause**: User hasn't crystallized their ideas yet
+**Solution**:
+- Ask open-ended questions: "What made you think of this?"
+- Probe for use cases: "Walk me through how someone would use this"
+- Be patient - this mode is for exploration
+- Multiple exchanges are normal and expected
+
+### Issue: Detecting 3+ distinct topics but user keeps adding more
+**Cause**: Brainstorming mode or unclear priorities
+**Solution** (inline):
+- Interrupt after 3+ topics detected (per multi-topic protocol)
+- Strongly suggest focusing on one topic
+- Alternative: Document all topics and help prioritize
+- Consider suggesting `/clavix:prd` for each topic separately
+
+### Issue: Conversation exceeds 20 exchanges without clarity
+**Cause**: Too exploratory without convergence
+**Solution**:
+- Suggest wrapping up: "We've covered a lot. Ready to `/clavix:summarize`?"
+- Or pivot to `/clavix:prd` for structured planning
+- Or focus conversation: "Let's nail down the core problem first"
+
+### Issue: User wants to switch topics mid-conversation
+**Cause**: New idea occurred or original topic wasn't right
+**Solution**:
+- Note what was discussed so far
+- Ask: "Should we continue with [original topic] or switch to [new topic]?"
+- Suggest summarizing current topic first before switching

package/dist/templates/slash-commands/roocode/summarize.md

@@ -9,15 +9,35 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Instructions
 
-1. Review the entire conversation and identify:
-   - **Problem/Goal**: What is the user trying to build or solve?
-   - **Key Requirements**: What features and functionality were discussed?
-   - **Technical Constraints**: Any technologies, integrations, or performance needs?
-   - **User Needs**: Who are the end users and what do they need?
-   - **Success Criteria**: How will success be measured?
-   - **Context**: Any important background or constraints?
-
-2. Generate TWO outputs:
+1. **Pre-Extraction Validation** - Check conversation completeness:
+
+   **Minimum viable requirements:**
+   - **Objective/Goal**: Is there a clear problem or goal stated?
+   - **Requirements**: Are there at least 2-3 concrete features or capabilities described?
+   - **Context**: Is there enough context about who/what/why?
+
+   **If missing critical elements:**
+   - Identify what's missing (e.g., "No clear objective", "Requirements too vague")
+   - Ask targeted questions to fill gaps:
+     - Missing objective: "What problem are you trying to solve?"
+     - Vague requirements: "Can you describe 2-3 specific things this should do?"
+     - No context: "Who will use this and in what situation?"
+   - **DO NOT** proceed to extraction until minimum viable requirements met
+
+   **Confidence indicators** (annotate extracted elements):
+   - **[HIGH]**: Explicitly stated multiple times with details
+   - **[MEDIUM]**: Mentioned once or inferred from context
+   - **[LOW]**: Assumed based on limited information
+
+2. Review the entire conversation and identify (with confidence indicators):
+   - **Problem/Goal** [confidence]: What is the user trying to build or solve?
+   - **Key Requirements** [confidence per requirement]: What features and functionality were discussed?
+   - **Technical Constraints** [confidence]: Any technologies, integrations, or performance needs?
+   - **User Needs** [confidence]: Who are the end users and what do they need?
+   - **Success Criteria** [confidence]: How will success be measured?
+   - **Context** [confidence]: Any important background or constraints?
+
+3. Generate TWO outputs:
 
    **Mini-PRD** (structured document):
    ```markdown
@@ -52,12 +72,18 @@ You are analyzing the conversation history and extracting optimized requirements
    [Success criteria and any important context]
    ```
 
-3. **CLEAR Framework Optimization** (automatic):
-   - After extracting the optimized prompt, it's analyzed using CLEAR framework
-   - Applies Conciseness, Logic, and Explicitness enhancements
-   - Displays both raw extraction and CLEAR-enhanced version
-   - Shows CLEAR scores and improvements made
-   - Saves CLEAR-optimized version as `clear-optimized-prompt.md`
+3. **CLEAR Framework Optimization** (automatic with labeled improvements):
+   - After extracting the optimized prompt, analyze using CLEAR framework
+   - Apply Conciseness, Logic, and Explicitness enhancements
+   - **Label all improvements** with CLEAR component tags:
+     - **[C]**: "Removed 12 conversational words, reduced from 45 to 28 words"
+     - **[L]**: "Restructured flow: context → requirements → constraints → success criteria"
+     - **[E]**: "Added explicit output format (React component), persona (senior dev), success metrics (load time < 2s)"
+   - Display both raw extraction and CLEAR-enhanced version
+   - Show CLEAR scores (before/after) and labeled improvements
+   - Save both versions:
+     - `optimized-prompt.md` (raw extraction)
+     - `clear-optimized-prompt.md` (CLEAR-enhanced with improvement notes)
 
 4. Highlight key insights discovered during the conversation.
 
@@ -78,12 +104,26 @@ You are analyzing the conversation history and extracting optimized requirements
 
 ## Quality Checks
 
-- ✅ Clear objective stated
-- ✅ Specific, actionable requirements
-- ✅ Technical constraints identified
-- ✅ Success criteria defined
-- ✅ User needs considered
-- ✅ CLEAR framework applied for AI consumption
+- Clear objective stated
+- Specific, actionable requirements
+- Technical constraints identified
+- Success criteria defined
+- User needs considered
+- CLEAR framework applied for AI consumption
+
+## Workflow Navigation
+
+**You are here:** Summarize (Conversation Extraction)
+
+**Common workflows:**
+- **Standard flow**: `/clavix:start` → [conversation] → `/clavix:summarize` → Use CLEAR-optimized prompt
+- **To implementation**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
+- **Standalone use**: [Any conversation] → `/clavix:summarize` → Extract and optimize
+
+**Related commands:**
+- `/clavix:start` - Begin conversational exploration (typical previous step)
+- `/clavix:plan` - Generate tasks from extracted mini-PRD (next step)
+- `/clavix:fast` or `/clavix:deep` - Further optimize the extracted prompt
 
 ## Example
 
@@ -97,3 +137,43 @@ Technical stack: React + TypeScript frontend, integrate with existing Salesforce
 
 Success: Sales managers can identify issues within 30 seconds of opening, dashboard loads in <2 seconds, 90% of team uses it daily within first month.
 ```
+
+## Troubleshooting
+
+### Issue: Pre-extraction validation fails (missing objective/requirements)
+**Cause**: Conversation didn't cover enough detail
+**Solution** (inline - DO NOT extract):
+- List what's missing specifically
+- Ask targeted questions to fill gaps
+- Only proceed to extraction after minimum viable requirements met
+- Show confidence indicators for what WAS discussed
+
+### Issue: Conversation covered multiple unrelated topics
+**Cause**: Exploratory discussion without focus
+**Solution**:
+- Ask user which topic to extract/focus on
+- Or extract all topics separately into different sections
+- Mark multi-topic extraction with [MULTI-TOPIC] indicator
+- Suggest breaking into separate PRDs for each topic
+
+### Issue: CLEAR optimization doesn't significantly improve extracted prompt
+**Cause**: Conversation was already well-structured and detailed
+**Solution**:
+- Minor improvements are normal for good conversations
+- Show CLEAR scores (should be high: >80%)
+- Still provide both versions but note that original extraction was already CLEAR
+
+### Issue: Low confidence indicators across all extracted elements
+**Cause**: Conversation was too vague or high-level
+**Solution** (inline):
+- Don't just extract with [LOW] markers everywhere
+- Ask follow-up questions to increase confidence
+- Or inform user: "Our conversation was exploratory. I recommend `/clavix:start` to go deeper, or `/clavix:prd` for structured planning"
+
+### Issue: Extracted prompt contradicts earlier conversation
+**Cause**: Requirements evolved during conversation
+**Solution**:
+- Use latest/final version of requirements
+- Note that requirements evolved
+- Ask user to confirm which version is correct
+- Suggest starting fresh with `/clavix:prd` if major contradictions exist