clavix 2.1.2 → 2.3.0

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

@@ -83,7 +83,7 @@ Generated by Clavix /clavix:implement
 
 ## Important Rules
 
-✅ **DO**:
+**DO**:
 - Read tasks.md to find the current task
 - Implement ONE task at a time
 - Mark tasks complete by changing `[ ]` to `[x]`
@@ -91,13 +91,88 @@ Generated by Clavix /clavix:implement
 - Reference the PRD for detailed requirements
 - Ask for clarification when tasks are ambiguous
 
-❌ **DON'T**:
+**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
 
 ```
@@ -113,6 +188,20 @@ Generated by Clavix /clavix:implement
    - 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
@@ -120,3 +209,59 @@ Generated by Clavix /clavix:implement
 - 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/cline/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/cline/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/cline/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