clavix 2.1.2 → 2.2.0

package/dist/templates/slash-commands/gemini/archive.toml

@@ -1,5 +1,6 @@
 description = "Archive completed PRD projects"
 prompt = """
+
 # Clavix Archive - PRD Project Archival
 
 You are helping the user archive completed PRD projects to keep their workspace organized.
@@ -44,7 +45,33 @@ You are helping the user archive completed PRD projects to keep their workspace
    - User wants to archive work-in-progress
    - Tasks are incomplete but project is done
 
-5. **List Archived Projects**:
+5. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION**
+   ```bash
+   clavix archive [project-name] --delete
+   ```
+
+   **WARNING**: This PERMANENTLY deletes the project. Cannot be restored.
+
+   **When to delete vs archive:**
+   - **DELETE**: Failed experiments, duplicate projects, test/demo data, abandoned prototypes with no value
+   - **ARCHIVE**: Completed work, incomplete but potentially useful work, anything you might reference later
+
+   **Delete decision tree:**
+   ```
+   Is this a failed experiment with no learning value? → DELETE
+   Is this a duplicate/test project with no unique info? → DELETE
+   Might you need to reference this code later? → ARCHIVE
+   Could this be useful for learning/reference? → ARCHIVE
+   Are you unsure? → ARCHIVE (safe default)
+   ```
+
+   **Safety confirmation required:**
+   - Shows project details and task status
+   - Requires typing project name to confirm
+   - Warns about permanent deletion
+   - Lists what will be permanently deleted
+
+6. **List Archived Projects**:
    ```bash
    clavix archive --list
    ```
@@ -60,14 +87,14 @@ You are helping the user archive completed PRD projects to keep their workspace
 
 ## When to Archive
 
-✅ **Good times to archive**:
+**Good times to archive:**
 - All implementation tasks are completed (`tasks.md` shows 100%)
 - Project has been deployed/shipped to production
 - Feature is complete and no more work planned
 - User explicitly requests archival
 - Old/abandoned projects that won't be continued
 
-❌ **Don't archive when**:
+**Don't archive when:**
 - Tasks are still in progress (unless using --force)
 - Project is actively being worked on
 - Future enhancements are planned in current tasks
@@ -128,6 +155,29 @@ You: "I'll restore it from the archive"
 Result: Project moved back to .clavix/outputs/user-authentication-system/
 ```
 
+### Workflow 4: Delete Failed Experiment
+```
+User: "I have a test project 'api-experiment-1' that I don't need anymore"
+You: "Is this something you might reference later, or can it be permanently deleted?"
+
+User: "It was just a quick test, no value. Delete it."
+You: "This will permanently delete the project. I'll run the delete command."
+
+     Run: clavix archive api-experiment-1 --delete
+
+System shows:
+  Project: api-experiment-1
+  Tasks: 3/5 completed
+  Files: full-prd.md, quick-prd.md, tasks.md
+
+  WARNING: This action is PERMANENT and CANNOT be undone.
+  Type the project name to confirm deletion: _
+
+User types: api-experiment-1
+
+Result: Project permanently deleted from .clavix/outputs/api-experiment-1/
+```
+
 ## AI Agent Guidelines
 
 When user mentions archiving or cleaning up projects:
@@ -152,6 +202,28 @@ When user mentions archiving or cleaning up projects:
    - Use `clavix archive --list` to show what's archived
    - Offer to restore if needed
 
+5. **Handle delete requests carefully**:
+   - Always ask if they want to delete or archive
+   - Explain that delete is permanent and irreversible
+   - Suggest archive as the safer default
+   - Use decision tree to help user decide
+   - Only proceed with `--delete` after clear confirmation
+   - Double-check it's truly no-value content (failed experiments, duplicates)
+
+## Workflow Navigation
+
+**You are here:** Archive (Project Cleanup)
+
+**Common workflows:**
+- **Complete workflow**: `/clavix:implement` → [all tasks done] → `/clavix:archive` → Clean workspace
+- **Review and archive**: `/clavix:archive` → [select completed project] → Archive
+- **Restore old work**: `/clavix:archive --list` → `/clavix:archive --restore [project]` → Resume
+
+**Related commands:**
+- `/clavix:implement` - Complete remaining tasks before archiving
+- `/clavix:plan` - Review task completion status
+- `/clavix:prd` - Start new project after archiving old one
+
 ## Tips
 
 - Archive keeps your active projects list clean and focused
@@ -159,4 +231,60 @@ When user mentions archiving or cleaning up projects:
 - Archive is searchable - you can still `grep` or find files in archive/
 - Regular archiving improves `/clavix:plan` and `/clavix:implement` performance
 - Use `--list` regularly to know what's been archived
-"""
+
+## Troubleshooting
+
+### Issue: No projects available to archive
+**Cause**: No projects in `.clavix/outputs/` OR all already archived
+**Solution**:
+- Run `clavix archive --list` to see archived projects
+- Check `.clavix/outputs/` for active projects
+- If none exist, no action needed
+
+### Issue: Trying to archive project with incomplete tasks
+**Cause**: User wants to archive but tasks aren't 100% done
+**Solution** (inline):
+- Warn: "Project has X incomplete tasks. Archive anyway?"
+- Show which tasks are incomplete
+- Suggest `--force` flag if user confirms
+- Recommend completing tasks first if they're actually unfinished (not scope-changed)
+
+### Issue: Cannot restore archived project (name conflict)
+**Cause**: Project with same name already exists in active outputs
+**Solution**:
+- Error: "Project '[name]' already exists in active outputs"
+- Suggest renaming one of them
+- Or archive the active one first, then restore
+- Or restore to different name (if CLI supports it)
+
+### Issue: Unsure whether to delete or archive
+**Cause**: User wants to clean up but uncertain about permanence
+**Solution**:
+- Use the decision tree in template
+- Default recommendation: ARCHIVE (safer)
+- Only suggest delete for: duplicates, failed experiments, test data
+- Remind: Archive is free, disk space is cheap, regret is expensive
+
+### Issue: Accidentally deleted project (used --delete instead of archive)
+**Cause**: User error or misunderstanding of --delete flag
+**Solution**:
+- Cannot be recovered from Clavix
+- Check if git history exists (if code was committed)
+- Check if user has backups
+- Learn: Use archive by default, delete only when absolutely certain
+
+### Issue: Archive directory getting too large
+**Cause**: Many archived projects accumulating
+**Solution**:
+- Archive is meant to grow - this is normal
+- Projects in archive don't affect performance
+- If truly concerned: Review archive, delete ancient/irrelevant projects
+- Or move very old archives to external backup storage
+
+### Issue: Archived project but forgot what it was about
+**Cause**: No naming convention or time passed
+**Solution**:
+- Read PRD in archived project: `.clavix/outputs/archive/[project]/full-prd.md`
+- PRD contains problem, goal, and features
+- Consider better naming conventions: date-feature format (e.g., "2024-01-user-auth")
+"""

package/dist/templates/slash-commands/gemini/deep.toml

@@ -1,5 +1,6 @@
 description = "Full CLEAR framework analysis (C, L, E, A, R components)"
 prompt = """
+
 # Clavix Deep Mode - Full CLEAR Framework Analysis
 
 You are helping the user perform a comprehensive deep analysis using the full CLEAR Framework (all 5 components: Concise, Logical, Explicit, Adaptive, Reflective).
@@ -28,21 +29,37 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
    - **Adaptiveness [A]**: Multiple variations and approaches
    - **Reflectiveness [R]**: Full validation and edge case analysis
 
-3. **Generate Comprehensive Output**:
+3. **Strategic Scope Detection** (before detailed analysis):
+
+   **Check for strategic concerns** by identifying keywords/themes:
+   - **Architecture**: system design, microservices, monolith, architecture patterns, scalability patterns
+   - **Security**: authentication, authorization, encryption, security, OWASP, vulnerabilities, threat model
+   - **Scalability**: load balancing, caching, database scaling, performance optimization, high availability
+   - **Infrastructure**: deployment, CI/CD, DevOps, cloud infrastructure, containers, orchestration
+   - **Business Impact**: ROI, business metrics, KPIs, stakeholder impact, market analysis
+
+   **If 3+ strategic keywords detected**:
+   Ask the user: "I notice this involves strategic decisions around [detected themes]. These topics benefit from PRD-style planning with business context and architectural considerations. Would you like to:
+   - Switch to `/clavix:prd` for comprehensive strategic planning (recommended)
+   - Continue with deep mode for prompt-level analysis only"
+
+   **If user chooses to continue**, proceed with deep analysis but remind them at the end that `/clavix:prd` is available for strategic planning.
+
+4. **Generate Comprehensive Output**:
 
-   a. **📊 CLEAR Assessment** (all 5 components with scores)
+   a. **CLEAR Assessment** (all 5 components with scores)
 
-   b. **✨ CLEAR-Optimized Prompt** (applying all components)
+   b. **CLEAR-Optimized Prompt** (applying all components)
 
-   c. **📝 CLEAR Changes Made** (labeled with [C], [L], [E], [A], [R])
+   c. **CLEAR Changes Made** (labeled with [C], [L], [E], [A], [R])
 
-   d. **🔄 Adaptive Variations [A]**:
+   d. **Adaptive Variations [A]**:
       - 2-3 alternative phrasings
       - Alternative structures (user story, job story, structured)
       - Temperature recommendations
       - Explain when each approach is most appropriate
 
-   e. **🤔 Reflection Checklist [R]**:
+   e. **Reflection Checklist [R]**:
       - Validation steps for accuracy
       - Edge cases to consider
       - "What could go wrong" analysis
@@ -59,14 +76,14 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
 
 ## Deep Mode Features
 
-✅ Include (Full CLEAR Framework):
+**Include (Full CLEAR Framework):**
 - **[C, L, E]**: All fast mode analysis (conciseness, logic, explicitness)
 - **[A] Adaptive**: Alternative phrasings, structures, flexibility, temperature
 - **[R] Reflective**: Validation checklist, edge cases, quality criteria, fact-checking
 - **CLEAR Assessment**: All 5 component scores
 - **CLEAR-labeled Changes**: Educational feedback showing which component improved what
 
-❌ Do NOT include (these belong in `/clavix:prd`):
+**Do NOT include (these belong in `/clavix:prd`):**
 - System architecture recommendations
 - Security best practices
 - Scalability strategy
@@ -98,12 +115,12 @@ Output:
 - How to handle session expiration during active use?
 
 ## Implementation Examples
-✅ Good:
+**Good:**
 - Prompt specifies authentication method, error handling, and accessibility requirements
 - Includes context about existing auth system and integration points
 - Defines measurable success criteria (load time, accessibility score)
 
-❌ Bad:
+**Bad:**
 - "Make a login page" - no context, constraints, or success criteria
 - Missing technical stack and integration requirements
 - No consideration of security or user experience
@@ -134,6 +151,20 @@ Output:
 - **Deep mode** (`/clavix:deep`): Full CLEAR (C, L, E, A, R) - comprehensive analysis with alternatives and validation
 - **PRD mode** (`/clavix:prd`): CLEAR-validated PRD generation - strategic planning with architecture decisions
 
+## Workflow Navigation
+
+**You are here:** Deep Mode (Comprehensive CLEAR Analysis)
+
+**Common workflows:**
+- **Thorough analysis**: `/clavix:deep` → Use optimized prompt + alternatives
+- **Escalate to strategic**: `/clavix:deep` → (detects strategic scope) → `/clavix:prd` → Plan → Implement → Archive
+- **From fast mode**: `/clavix:fast` → (suggests) `/clavix:deep` → Full analysis with A & R components
+
+**Related commands:**
+- `/clavix:fast` - Quick CLEAR improvements (C, L, E only)
+- `/clavix:prd` - Strategic PRD generation for architecture/business decisions
+- `/clavix:start` - Conversational mode for exploring unclear requirements
+
 ## Tips
 
 - **Apply full CLEAR framework** systematically: all 5 components
@@ -142,4 +173,34 @@ Output:
 - Use **[A] Adaptive** to explore alternative approaches
 - Use **[R] Reflective** to identify edge cases and validation needs
 - For architecture, security, and scalability, recommend `/clavix:prd`
-"""
+
+## Troubleshooting
+
+### Issue: Strategic scope detected but user wants to continue with deep mode
+**Cause**: User prefers deep analysis over PRD generation
+**Solution**:
+- Proceed with deep mode as requested
+- Remind at end that `/clavix:prd` is available for strategic planning
+- Focus on prompt-level CLEAR analysis, exclude architecture recommendations
+
+### Issue: Too many alternative variations making output overwhelming
+**Cause**: Adaptive component generating many options
+**Solution**:
+- Limit to 2-3 most distinct alternatives
+- Focus on meaningfully different approaches (not minor wording changes)
+- Group similar variations together
+
+### Issue: Reflective validation finding too many edge cases
+**Cause**: Complex prompt with many potential failure modes
+**Solution**:
+- Prioritize most likely or highest-impact edge cases
+- Group related edge cases
+- Suggest documenting all edge cases in PRD for complex projects
+
+### Issue: Deep analysis still feels insufficient for complex project
+**Cause**: Project needs strategic planning, not just prompt analysis
+**Solution**:
+- Switch to `/clavix:prd` for comprehensive planning
+- Deep mode is for prompts, PRD mode is for projects
+- Use PRD workflow: PRD → Plan → Implement
+"""

package/dist/templates/slash-commands/gemini/fast.toml

@@ -1,5 +1,6 @@
 description = "CLEAR-guided quick improvements (C, L, E components)"
 prompt = """
+
 # 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.
@@ -26,15 +27,25 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
    - **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**: Check if the prompt needs deep analysis:
-   - Is it less than 20 characters?
-   - Missing 3+ critical elements (context, tech stack, success criteria, user needs, expected output)?
-   - Contains vague scope words ("app", "system", "project") without context?
-   - **Low CLEAR scores** (Conciseness < 60%, Logic < 60%, Explicitness < 50%)
+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)
 
-   If YES to any: **Recommend `/clavix:deep` instead** and explain which CLEAR component needs deeper analysis. Ask the user if they want to:
-   - Switch to deep mode (recommended)
-   - Continue with fast mode (at their own risk)
+   **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
@@ -52,13 +63,13 @@ An academically-validated prompt engineering framework by Dr. Leo Lo (University
 
 ## Fast Mode Features
 
-✅ Include (CLEAR C, L, E):
+**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):
+**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`)
@@ -69,9 +80,9 @@ If user provides: "Please could you maybe help me create a login page?"
 
 Output:
 ```
-## 🎯 CLEAR Analysis (Fast Mode)
+## CLEAR Analysis (Fast Mode)
 
-### 📊 CLEAR Framework Assessment:
+### CLEAR Framework Assessment:
 
 [C] Conciseness: 45%
     • 4 unnecessary pleasantries detected ("Please", "could you", "maybe", "help me")
@@ -87,11 +98,11 @@ Output:
 
 Overall CLEAR Score: 51% (needs-improvement)
 
-💡 Recommendation:
+Recommendation:
 For Adaptive variations (A) and Reflective validation (R), use:
   clavix deep "<your prompt>"
 
-### ✨ CLEAR-Optimized Prompt:
+### CLEAR-Optimized Prompt:
 
 Objective: Build a secure user authentication login page
 
@@ -116,13 +127,27 @@ Success Criteria:
 - Invalid credentials show appropriate errors
 - Page is accessible via keyboard navigation
 
-### 📝 CLEAR Changes Made:
+### 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
@@ -131,4 +156,27 @@ Success Criteria:
 - 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/gemini/implement.toml

@@ -1,5 +1,6 @@
 description = "Execute tasks from the implementation plan"
 prompt = """
+
 # Clavix Implement - AI-Assisted Task Execution
 
 You are helping the user implement tasks from their task plan with AI assistance.
@@ -80,7 +81,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]`
@@ -88,13 +89,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
 
 ```
@@ -110,6 +186,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
@@ -117,4 +207,60 @@ 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
+"""