clavix 5.7.0 → 5.8.0

package/dist/templates/slash-commands/_canonical/archive.md

@@ -274,7 +274,7 @@ Result: Project permanently deleted
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -524,7 +524,7 @@ I'll explain what's wrong and what you might need to do:
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/improve.md

@@ -5,6 +5,24 @@ description: Analyze and improve prompts with auto-detected depth
 
 # Clavix: Improve Your Prompt
 
+---
+
+## What This Does
+
+When you run `/clavix:improve`, I:
+1. **Analyze your prompt quality** - 6-dimension assessment (Clarity, Efficiency, Structure, Completeness, Actionability, Specificity)
+2. **Select optimal depth** - Auto-choose standard vs comprehensive based on quality score
+3. **Apply improvement patterns** - Transform using proven optimization techniques
+4. **Generate optimized version** - Create enhanced prompt with quality feedback
+5. **Save for implementation** - Store in `.clavix/outputs/prompts/` for `/clavix:implement`
+
+**Smart Depth Selection:**
+- **Quality ≥ 75%**: Comprehensive depth (add polish and enhancements)
+- **Quality 60-74%**: User choice (borderline quality)
+- **Quality < 60%**: Standard depth (focus on basic fixes)
+
+---
+
 ## Important: This is Planning Mode
 
 This is a prompt improvement workflow. Your job is to ANALYZE and IMPROVE the prompt, then STOP.
@@ -504,7 +522,7 @@ Wait for the user to decide what to do next.
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -1,36 +1,36 @@
 ---
 name: "Clavix: Plan"
-description: Generate implementation task breakdown from PRD
+description: Generate detailed technical implementation tasks from PRD and codebase context
 ---
 
-# Clavix: Plan Your Tasks
+# Clavix: Plan Your Implementation
 
-I'll turn your PRD into a step-by-step task list. Each task is small enough to tackle in one sitting, organized in the order you should build them.
+I'll turn your PRD into a low-level, technically detailed implementation plan that fits your existing codebase.
 
 ---
 
 ## What This Does
 
 When you run `/clavix:plan`, I:
-1. **Read your PRD** - Understand what needs to be built
-2. **Break it into tasks** - Small, actionable pieces
-3. **Organize into phases** - Logical groupings (setup, core features, polish)
-4. **Create tasks.md** - Your implementation roadmap
-5. **Assign task IDs** - For tracking progress
+1. **Analyze your Codebase** - Understand your existing architecture, patterns, and stack
+2. **Read your PRD** - Understand new requirements
+3. **Bridge the Gap** - Map requirements to specific files and existing components
+4. **Generate Technical Tasks** - detailed, file-specific instructions
+5. **Create tasks.md** - Your comprehensive engineering roadmap
 
 **I create the plan. I don't build anything yet.**
 
 ---
 
-## CLAVIX MODE: Planning Only
+## CLAVIX MODE: Technical Planning
 
-**I'm in planning mode. Creating your task breakdown.**
+**I'm in planning mode. Creating your engineering roadmap.**
 
 **What I'll do:**
-- ✓ Read and understand your PRD
-- ✓ Generate structured task breakdown
-- ✓ Organize tasks into logical phases
-- ✓ Create clear, actionable task descriptions
+- ✓ Analyze existing code structure & patterns
+- ✓ Map PRD features to specific technical implementations
+- ✓ Define exact file paths and signatures
+- ✓ Create "Implementation Notes" for each task
 - ✓ Save tasks.md for implementation
 
 **What I won't do:**
@@ -38,7 +38,7 @@ When you run `/clavix:plan`, I:
 - ✗ Start implementing features
 - ✗ Create actual components
 
-**I'm planning what to build, not building it.**
+**I'm planning strictly *how* to build it.**
 
 For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
 
@@ -46,23 +46,22 @@ For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
 
 ## Self-Correction Protocol
 
-**DETECT**: If you find yourself doing any of these 6 mistake types:
+**DETECT**: If you find yourself doing any of these mistake types:
 
 | Type | What It Looks Like |
 |------|--------------------|
-| 1. Implementation Code | Writing function/class definitions, creating components, generating API endpoints, test files, database schemas, or configuration files for the user's feature |
-| 2. Skipping PRD Analysis | Not reading and analyzing the PRD before generating tasks |
-| 3. Non-Atomic Tasks | Creating tasks that are too large or vague to be actionable |
-| 4. Missing Task IDs | Not assigning proper task IDs and references |
-| 5. Missing Phase Organization | Not organizing tasks into logical implementation phases |
-| 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing task formats |
+| 1. Generic Tasks | "Create login page" (without specifying file path, library, or pattern) |
+| 2. Ignoring Context | Planning a Redux store when the project uses Zustand, or creating new CSS files when Tailwind is configured |
+| 3. Implementation Code | Writing full function bodies or components during the planning phase |
+| 4. Missing Task IDs | Not assigning proper task IDs for tracking |
+| 5. Capability Hallucination | Claiming features Clavix doesn't have |
 
-**STOP**: Immediately halt the incorrect action
+**STOP**: Immediately halt the incorrect action.
 
 **CORRECT**: Output:
-"I apologize - I was [describe mistake]. Let me return to task breakdown generation."
+"I apologize - I was [describe mistake]. Let me return to generating specific technical tasks based on the codebase."
 
-**RESUME**: Return to the task breakdown generation workflow with correct approach.
+**RESUME**: Return to the workflow with correct context-aware approach.
 
 ---
 
@@ -70,10 +69,10 @@ For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
 
 **Before starting task breakdown, output:**
 ```
-**CLAVIX MODE: Task Planning**
+**CLAVIX MODE: Technical Planning**
 Mode: planning
-Purpose: Generating implementation task breakdown from PRD
-Implementation: BLOCKED - I will create tasks, not implement them
+Purpose: Generating low-level engineering tasks from PRD & Codebase
+Implementation: BLOCKED - I will create the plan, not the code
 ```
 
 ---
@@ -82,149 +81,94 @@ Implementation: BLOCKED - I will create tasks, not implement them
 
 ### Part A: Agent Execution Protocol
 
-**As an AI agent, you have two execution options:**
-
-#### **Agent Execution Protocol (v5)**
-
-1. **Validate prerequisites**:
-   - Check if `.clavix/outputs/` directory exists
-   - Look for PRD artifacts in this order:
-     1. **Project directories first**: Check `.clavix/outputs/<project-name>/` folders for `full-prd.md`, `quick-prd.md`, `mini-prd.md`, or `optimized-prompt.md`
-     2. **Legacy fallback**: If no project directories found, check `.clavix/outputs/summarize/` for `mini-prd.md` or `optimized-prompt.md` (backwards compatibility)
-   - **If multiple projects found**: List them and ask user which one to plan
-   - **If not found**: Error inline - "No PRD found in `.clavix/outputs/`. Use `/clavix:prd` or `/clavix:summarize` first."
-
-2. **Read the PRD** from detected location (project directory or legacy `summarize/` folder)
-
-3. **Generate task breakdown** following Part B principles
-
-4. **Create `tasks.md`** using your Write tool with format specified in "Task Format Reference" below
-
-5. **Save to**: `.clavix/outputs/[project-name]/tasks.md`
-
-6. **Use exact format** (task IDs, checkboxes, structure)
-
-#### **Alternative: Generate Tasks Directly** (If agent has full PRD context)
-
-If you have the full PRD content in memory and want to generate tasks directly:
-
-1. **Read the PRD** from `.clavix/outputs/[project-name]/`
-2. **Generate task breakdown** following Part B principles
-3. **Create `tasks.md`** with format specified in "Task Format Reference" below
-4. **Save to**: `.clavix/outputs/[project-name]/tasks.md`
-5. **Use exact format** (task IDs, checkboxes, structure)
-
-### Part B: Behavioral Guidance (Task Breakdown Strategy)
-
-3. **How to structure tasks** (optimized task breakdown):
-
-   **Task Granularity Principles:**
-   - **Clarity**: Each task = 1 clear action (not "Build authentication system", but "Create user registration endpoint")
-   - **Structure**: Tasks flow in implementation order (database schema → backend logic → frontend UI)
-   - **Actionability**: 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)
-
-   **Task Dependency Management:**
-   - **Explicit ordering**: Tasks within a phase should be ordered by execution sequence
-   - **Dependency markers**: Use `(depends: task-id)` for explicit dependencies
-   - **Common dependency patterns**:
-     - Database schema → Models → API endpoints → UI components
-     - Authentication → Protected routes → User-specific features
-     - Core utilities → Features that use them → Integration tests
-   - **Anti-pattern**: Avoid circular dependencies (A depends on B, B depends on A)
-   - **Parallel tasks**: If two tasks have no dependencies, they can be worked on simultaneously
-
-4. **Review and customize generated tasks**:
-   - The command will generate `tasks.md` in the PRD folder
-   - Tasks are organized into logical phases with quality 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. **Task Quality Labeling** (optional, for education):
-   When reviewing tasks, you can annotate improvements:
-   - **[Clarity]**: "Split vague 'Add UI' into 3 concrete tasks"
-   - **[Structure]**: "Reordered tasks: database schema before API endpoints"
-   - **[Actionability]**: "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 ID: phase-1-feature-name-1
-
-- [ ] Task 2 description
-  Task ID: phase-1-feature-name-2
-
-- [ ] Task 3 description
-  Task ID: phase-1-feature-name-3
-
-## Phase 2: Another Feature
-
-- [ ] Task 4 description
-  Task ID: phase-2-another-feature-1
-
-- [ ] Task 5 description
-  Task ID: phase-2-another-feature-2
+**As an AI agent, you must follow this strict sequence:**
+
+#### **Phase 1: Context Analysis (CRITICAL)**
+*Before reading the PRD, understand the "Team's Coding Method".*
+
+1. **Scan Directory Structure**:
+   - Run `ls -R src` (or relevant folders) to see the file layout.
+2. **Read Configuration**:
+   - Read `package.json` to identify dependencies (React? Vue? Express? Tailwind? Prisma?).
+   - Read `tsconfig.json` or similar to understand aliases and strictness.
+3. **Identify Patterns**:
+   - Open 1-2 representative files (e.g., a component, a service, a route).
+   - **Determine**:
+     - How is state managed? (Context, Redux, Zustand?)
+     - How is styling done? (CSS Modules, Tailwind, SCSS?)
+     - How are API calls made? (fetch, axios, custom hooks?)
+     - Where are types defined?
+4. **Output Summary**: Briefly state the detected stack (e.g., "Detected: Next.js 14 (App Router), Tailwind, Prisma, Zod").
+
+#### **Phase 2: PRD Ingestion**
+1. **Locate PRD**:
+   - Check `.clavix/outputs/<project-name>/` for `full-prd.md`, `quick-prd.md`, etc.
+   - If missing, check legacy `.clavix/outputs/summarize/`.
+2. **Read PRD**: Ingest the requirements.
+
+#### **Phase 3: Task Generation**
+1. **Synthesize**: Combine [PRD Requirements] + [Codebase Patterns].
+2. **Draft Tasks**: Create tasks that specify *exactly* what to change in the code.
+3. **Create `tasks.md`**: Use the format in "Task Format Reference".
+4. **Save to**: `.clavix/outputs/[project-name]/tasks.md`.
+
+### Part B: Behavioral Guidance (Technical Specificity)
+
+**Your goal is "Low-Level Engineering Plans", not "High-Level Management Plans".**
+
+1. **Specific File Paths**:
+   - **Bad**: "Create a user profile component."
+   - **Good**: "Create `src/components/user/UserProfile.tsx`. Export as default."
+
+2. **Technical Constraints**:
+   - **Bad**: "Add validation."
+   - **Good**: "Use `zod` schema in `src/schemas/user.ts`. Integrate with `react-hook-form`."
+
+3. **Respect Existing Architecture**:
+   - If the project uses a `services/` folder for API calls, do **not** put `fetch` calls directly in components.
+   - If the project uses `shadcn/ui`, instruct to use those primitives, not raw HTML.
+
+4. **Granularity**:
+   - Each task should be a single logical unit of work (approx. 20-40 mins).
+   - Separate "Backend API" from "Frontend UI" tasks.
+   - Separate "Type Definition" from "Implementation" if complex.
 
 ---
 
-*Generated by Clavix /clavix:plan*
-```
-
-## Task Format Reference (For Agent-Direct Generation)
+## Task Format Reference
 
-**If you're generating tasks directly (Option 2), follow this exact format:**
+**You must generate `tasks.md` using this exact format:**
 
 ### File Structure
 ```markdown
-# Implementation Tasks
+# Implementation Plan
 
 **Project**: {project-name}
 **Generated**: {ISO timestamp}
 
+## Technical Context & Standards
+*Detected Stack & Patterns*
+- **Framework**: {e.g., Next.js 14 App Router}
+- **Styling**: {e.g., Tailwind CSS + shadcn/ui}
+- **State**: {e.g., Zustand (stores in /src/store)}
+- **API**: {e.g., Server Actions + Prisma}
+- **Conventions**: {e.g., "kebab-case files", "Zod for validation"}
+
 ---
 
 ## Phase {number}: {Phase Name}
 
-- [ ] {Task description} (ref: {PRD Section})
+- [ ] **{Task Title}** (ref: {PRD Section})
   Task ID: {task-id}
+  > **Implementation**: Create/Edit `{file/path}`.
+  > **Details**: {Technical instruction, e.g., "Use `useAuth` hook. Ensure error handling matches `src/utils/error.ts`."}
 
 ## Phase {number}: {Next Phase}
 
-- [ ] {Task description}
+- [ ] **{Task Title}**
   Task ID: {task-id}
+  > **Implementation**: Modify `{file/path}`.
+  > **Details**: {Specific logic requirements}
 
 ---
 
@@ -232,119 +176,50 @@ The generated `tasks.md` will look like:
 ```
 
 ### Task ID Format
-
 **Pattern**: `phase-{phase-number}-{sanitized-phase-name}-{task-counter}`
+(e.g., `phase-1-setup-01`, `phase-2-auth-03`)
 
-**Rules**:
-- Phase number: Sequential starting from 1
-- Sanitized phase name: Lowercase, spaces→hyphens, remove special chars
-- Task counter: Sequential within phase, starting from 1
-
-**Examples**:
-- Phase "Setup & Configuration" → Task 1 → `phase-1-setup-configuration-1`
-- Phase "User Authentication" → Task 3 → `phase-2-user-authentication-3`
-- Phase "API Integration" → Task 1 → `phase-3-api-integration-1`
-
-### Checkbox Format
-
-**Always use**: `- [ ]` for incomplete tasks (space between brackets)
-**Completed tasks**: `- [x]` (lowercase x, no spaces)
-
-### Task Description Format
-
-**Basic**: `- [ ] {Clear, actionable description}`
-**With reference**: `- [ ] {Description} (ref: {PRD Section Name})`
-**With dependency**: `- [ ] {Description} (depends: {task-id})`
-**Combined**: `- [ ] {Description} (ref: {Section}) (depends: {task-id})`
-
-**Example**:
-```markdown
-- [ ] Create user registration API endpoint (ref: User Management)
-  Task ID: phase-1-authentication-1
-
-- [ ] Add JWT token validation middleware (depends: phase-1-authentication-1)
-  Task ID: phase-1-authentication-2
-```
-
-### Task ID Placement
-
-**Critical**: Task ID must be on the line immediately after the task description
-**Format**: `  Task ID: {id}` (2 spaces indent)
-
-### Phase Header Format
-
-**Pattern**: `## Phase {number}: {Phase Name}`
-**Must have**: Empty line before and after phase header
-
-### File Save Location
-
-**Path**: `.clavix/outputs/{project-name}/tasks.md`
-**Create directory if not exists**: Yes
-**Overwrite if exists**: Only with explicit user confirmation or `--overwrite` flag
+### Checklist Rules
+- Use `- [ ]` for pending.
+- Use `- [x]` for completed.
+- **Implementation Note**: The `> **Implementation**` block is REQUIRED. It forces you to think about *where* the code goes.
 
 ---
 
 ## After Plan Generation
 
-After creating the task breakdown, I present it and ask for verification:
-
-**What I'll show:**
-- Summary of phases and task count
-- First few tasks from each phase
-- Any dependencies detected
-
-**What I'll ask:**
-> "Here's your task breakdown. Before you start implementing, please verify:
-> 1. Does this capture everything from your PRD?
-> 2. Are the tasks in the right order?
-> 3. Is the granularity right (not too big, not too small)?
+Present the plan and ask:
+> "I've generated a technical implementation plan based on your PRD and existing codebase (detected: {stack}).
 >
-> What would you like to do next?"
-
-**Your options:**
-1. Start implementing with `/clavix:implement`
-2. Edit tasks.md to adjust tasks
-3. Regenerate with different granularity
-4. Go back and refine the PRD first
+> **Please Verify**:
+> 1. Did I correctly identify the file structure and patterns?
+> 2. Are the specific file paths correct?
+> 3. Is the order of operations logical (e.g., Database -> API -> UI)?
+>
+> Type `/clavix:implement` to start coding, or tell me what to adjust."
 
 ---
 
 ## Workflow Navigation
 
-**You are here:** Plan (Task Breakdown)
-
-**State markers for workflow continuity:**
-- If user came from `/clavix:prd`: Full PRD available, use comprehensive task breakdown
-- If user came from `/clavix:summarize`: Mini-PRD available, may need simpler task structure
-- If PRD has many features: Consider grouping by feature in phases
-- If PRD has dependencies: Ensure task ordering reflects them
-
-**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`
+**You are here:** Plan (Technical Task Breakdown)
 
-**After completion, guide user to:**
-- `/clavix:implement` - Start executing tasks (recommended next step)
-- Edit `tasks.md` - If they want to adjust task order or granularity
+**Pre-requisites**:
+- A PRD (from `/clavix:prd`)
+- An existing codebase (or empty folder structure)
 
-**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)
+**Next Steps**:
+- `/clavix:implement`: Execute the tasks one by one.
+- **Manual Edit**: You can edit `.clavix/outputs/.../tasks.md` directly if you want to change the architecture.
 
-## Tips
-
-- Tasks are automatically optimized for clarity, structure, and actionability
-- Each task is concise and actionable
-- Tasks can reference specific PRD sections
-- Supports mini-PRD outputs from `/clavix:summarize`
-- You can manually edit tasks.md before implementing
-- Use `--overwrite` flag to regenerate if needed
+## Tips for Agents
+- **Don't guess**. If you don't see a directory, don't reference it.
+- **Check imports**. If `src/components/Button` exists, tell the user to reuse it.
+- **Be pedantic**. Developers prefer specific instructions like "Export interface `User`" over "Create a type".
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
@@ -362,99 +237,13 @@ After creating the task breakdown, I present it and ask for verification:
 
 ## Troubleshooting
 
-### Issue: No PRD found in `.clavix/outputs/`
-**Cause**: User hasn't generated a PRD yet
-
-**Agent recovery**:
-1. Check if `.clavix/outputs/` directory exists:
-   ```bash
-   ls .clavix/outputs/
-   ```
-2. If directory doesn't exist or is empty:
-   - Error: "No PRD artifacts found in `.clavix/outputs/`"
-   - Suggest recovery options:
-     - "Generate PRD with `/clavix:prd` for comprehensive planning"
-     - "Extract mini-PRD from conversation with `/clavix:summarize`"
-3. Do NOT proceed with plan generation without PRD
-
-### Issue: Generated tasks are too granular (100+ tasks)
-**Cause**: Over-decomposition or large project scope
-
-**Agent recovery**:
-1. Review generated tasks in `tasks.md`
-2. Identify micro-tasks that can be combined
-3. Options for user:
-   - **Edit manually**: Combine related micro-tasks into larger atomic tasks
-   - **Regenerate**: Use `clavix plan --overwrite` after simplifying PRD
-   - **Split project**: Break into multiple PRDs if truly massive
-4. Guideline: Each task should be 15-60 minutes, not 5 minutes
-5. Combine setup/configuration tasks that belong together
-
-### Issue: Generated tasks are too high-level (only 3-4 tasks)
-**Cause**: PRD was too vague or task breakdown too coarse
-
-**Agent recovery**:
-1. Read the PRD to assess detail level
-2. If PRD is vague:
-   - Suggest: "Let's improve the PRD with `/clavix:improve --comprehensive` first"
-   - Then regenerate tasks with `clavix plan --overwrite`
-3. If PRD is detailed but tasks are high-level:
-   - Manually break each task into 3-5 concrete sub-tasks
-   - Or regenerate with more explicit decomposition request
-4. Each task should have clear, testable deliverable
-
-### Issue: Tasks don't follow logical dependency order
-**Cause**: Generator didn't detect dependencies correctly OR agent-generated tasks weren't ordered
-
-**Agent recovery**:
-1. Review task order in `tasks.md`
-2. Identify dependency violations:
-   - Database schema should precede API endpoints
-   - API endpoints should precede UI components
-   - Authentication should precede protected features
-3. Manually reorder tasks in `tasks.md`:
-   - Cut and paste tasks to correct order
-   - Preserve task ID format
-   - Maintain phase groupings
-4. Follow structure principle: ensure sequential coherence
-
-### Issue: Tasks conflict with PRD or duplicate work
-**Cause**: Misinterpretation of PRD or redundant task generation
-
-**Agent recovery**:
-1. Read PRD and tasks.md side-by-side
-2. Identify conflicts or duplicates
-3. Options:
-   - **Remove duplicates**: Delete redundant tasks from tasks.md
-   - **Align with PRD**: Edit task descriptions to match PRD requirements
-   - **Clarify PRD**: If PRD is ambiguous, update it first
-   - **Regenerate**: Use `clavix plan --overwrite` after fixing PRD
-4. Ensure each PRD feature maps to tasks
-
-### Issue: `tasks.md` already exists, unsure if should regenerate
-**Cause**: Previous plan exists for this PRD
-
-**Agent recovery**:
-1. Read existing `tasks.md`
-2. Count completed tasks (check for `[x]` checkboxes)
-3. Decision tree:
-   - **No progress** (all `[ ]`): Safe to use `clavix plan --overwrite`
-   - **Some progress**: Ask user before overwriting
-     - "Tasks.md has {X} completed tasks. Regenerating will lose this progress. Options:
-       1. Keep existing tasks.md and edit manually
-       2. Overwrite and start fresh (progress lost)
-       3. Cancel plan generation"
-   - **Mostly complete**: Recommend NOT overwriting
-4. If user confirms overwrite: Run `clavix plan --project {name} --overwrite`
-
-### Issue: CLI command fails or no output
-**Cause**: Missing dependencies, corrupted PRD file, or CLI error
-
-**Agent recovery**:
-1. Check CLI error output
-2. Common fixes:
-   - Verify PRD file exists and is readable
-   - Check `.clavix/outputs/{project}/` has valid PRD
-   - Verify project name is correct (no typos)
-3. Try with explicit project: `clavix plan --project {exact-name}`
-4. If persistent: Inform user to check Clavix installation
+### Issue: "I don't know the codebase"
+**Cause**: Agent skipped Phase 1 (Context Analysis).
+**Fix**: Force the agent to run `ls -R` and read `package.json` before generating tasks.
+
+### Issue: Tasks are too generic ("Add Auth")
+**Cause**: Agent ignored the "Implementation Note" requirement.
+**Fix**: Regenerate with: "Refine the plan. Add specific file paths and implementation details to every task."
+
+### Issue: No PRD found
+**Fix**: Run `/clavix:prd` first.

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

@@ -344,7 +344,7 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}