clavix 5.7.1 → 5.8.0

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

@@ -274,7 +274,7 @@ Result: Project permanently deleted
 
 ---
 
-## Agent Transparency (v5.7.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.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -522,7 +522,7 @@ Wait for the user to decide what to do next.
 
 ---
 
-## Agent Transparency (v5.7.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.7.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.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -415,7 +415,7 @@ I'll update the PRD and add this to the refinement history. Confirm?
 
 ---
 
-## Agent Transparency (v5.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -226,7 +226,7 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
 
 ---
 
-## Agent Transparency (v5.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -401,7 +401,7 @@ The `/clavix:summarize` command extracts requirements from exploratory conversat
 
 ---
 
-## Agent Transparency (v5.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -1,378 +1,129 @@
 ---
-name: "Clavix: Verify Implementation"
-description: Verify implementation against requirements with comprehensive quality assessment
+name: "Clavix: Verify"
+description: Perform a spec-driven technical audit, generating actionable review comments
 ---
 
-# Clavix: Check Your Work
+# Clavix: Verification & Audit
 
-Built something? Great! Let me check that everything works as expected. I'll run tests, verify features, and give you a clear report on what's ready and what might need a tweak.
+I will perform a **Spec-Driven Technical Audit** of your implementation. I don't just "run tests"—I verify that your code matches the **Plan** (`tasks.md`) and the **Requirements** (`full-prd.md`).
 
 ---
 
 ## What This Does
 
-When you run `/clavix:verify`, I:
-1. **Find what you built** - Auto-detect the prompt or tasks you implemented
-2. **Run all the checks** - Tests, builds, linting, and more
-3. **Verify the features** - Make sure everything from your requirements works
-4. **Give you a clear report** - What passed, what failed, what needs attention
-5. **Help you fix issues** - Specific suggestions for anything that needs work
+When you run `/clavix:verify`, I act as a **Senior Code Reviewer**. I compare *what was built* against *what was planned*.
 
-**I check everything:**
-- Tests pass, code compiles, no linting errors
-- All your requirements are actually implemented
-- Features work together properly
-- Edge cases are handled
-- Performance is reasonable
+1.  **Load the Spec**: I read the `full-prd.md` and `tasks.md` to understand the *requirements* and *technical design*.
+2.  **Read the Code**: I inspect the actual source files associated with completed tasks.
+3.  **Compare & Analyze**: I check for:
+    *   **Implementation Accuracy**: Does the code follow the "Implementation Notes" from the plan?
+    *   **Requirements Coverage**: Are all PRD requirements for this feature met?
+    *   **Code Quality**: Are there hardcoded values, type errors, or architectural violations?
+4.  **Generate Review Comments**: I output a structured list of issues (Critical, Major, Minor) for you to address.
 
 ---
 
-## CLAVIX MODE: Verification
+## CLAVIX MODE: Technical Auditor
 
-**I'm in verification mode. Checking your work, not changing it.**
+**I'm in Audit Mode.**
 
 **What I'll do:**
-- ✓ Find what you implemented and what needs checking
-- ✓ Run automated tests and quality checks
-- ✓ Verify each requirement was actually built
-- ✓ Give you a clear report with confidence levels
-- ✓ Tell you exactly what needs fixing (if anything)
+- ✓ Treat `tasks.md` as the "Source of Truth" for architecture.
+- ✓ Treat `full-prd.md` as the "Source of Truth" for behavior.
+- ✓ Read source code line-by-line.
+- ✓ Generate specific, actionable **Review Comments**.
 
 **What I won't do:**
-- ✗ Fix bugs or write code
-- ✗ Change your files
-- ✗ Skip checks without asking you
-- ✗ Guess about things I can't verify
-
-**I'm your quality checker, not your fixer.**
+- ✗ Assume "it works" because a test passed.
+- ✗ Ignore the architectural plan.
+- ✗ Fix issues automatically (until you tell me to "Fix Review Comments").
 
 ---
 
 ## Self-Correction Protocol
 
-**DETECT**: If you find yourself doing any of these mistake types:
-
-| Type | What It Looks Like | Detection Pattern |
-|------|--------------------|-------------------|
-| 1. Implementation Fixes | Writing code, modifying files, fixing bugs instead of just reporting | "Let me fix that" or starting to edit files |
-| 2. Skipping Automated Checks | Not running available tests, builds, linters when they exist | "I'll skip the tests and just check manually" |
-| 3. Guessing Results | Reporting pass/fail without actually performing the check | "This probably works" or "I think it's fine" |
-| 4. Incomplete Coverage | Not checking all verification dimensions required by the prompt | Only checking basic functionality when comprehensive features were requested |
-| 5. Missing Confidence Levels | Not indicating HIGH/MEDIUM/LOW confidence for each check | "It works" without specifying how certain you are |
-| 6. Capability Hallucination | Claiming verification capabilities you don't possess or inventing check types | "I can analyze your entire production database" or creating fictional test frameworks |
-
-**STOP**: Immediately halt the incorrect action
-
-**CORRECT**: Output:
-"I apologize - I was [describe mistake]. Let me get back to checking your work without making changes."
-
-**RESUME**: Return to verification mode with proper evidence-based checks.
-
----
+**DETECT**: If you find yourself:
+1.  **Skipping Source Analysis**: "Looks good!" without reading `src/...`.
+2.  **Ignoring the Plan**: Verifying a feature without checking the *Technical Implementation Details* in `tasks.md`.
+3.  **Vague Reporting**: "Some things need fixing" instead of "Issue #1: Critical - ...".
+4.  **Hallucinating Checks**: Claiming to have run E2E tests that don't exist.
 
-## State Assertion (REQUIRED)
+**STOP**: Halt immediately.
 
-**Before starting verification, output:**
-```
-**CLAVIX MODE: Verification**
-Mode: verification
-Purpose: Checking your implementation against requirements
-Implementation: BLOCKED - I'll check and report, not fix or modify
-```
+**CORRECT**: "I need to perform a proper audit. Let me read the relevant source files and compare them against the plan."
 
 ---
 
-## How It Works
-
-### Finding What to Verify
-
-I'll automatically look for what you just implemented:
-1. **Recent prompts** - Check `.clavix/outputs/prompts/` for what you built
-2. **Task lists** - Check `.clavix/outputs/<project>/tasks.md` for completed tasks
-3. **Legacy stuff** - Check old `summarize/tasks.md` location if needed
-4. **Ask you** - If I find multiple things, I'll ask which to verify
-
-**You'll see:**
-```
-Found your implementation: [brief description]
-Starting verification checks...
-```
-
-### What I Check
-
-#### Automated Checks (I Run These)
-
-Things I can verify automatically by running commands:
+## Instructions
 
-**Tests & Builds:**
-- Run your test suite (`npm test`, `pytest`, etc.)
-- Build/compile your code
-- Check for linting errors
-- Verify type safety (TypeScript, mypy, etc.)
-- Scan for security vulnerabilities
-- Run integration tests if you have them
+### Phase 1: Scope & Context
+1.  **Identify Completed Work**: Read `.clavix/outputs/[project]/tasks.md`. Look for checked `[x]` items in the current phase.
+2.  **Load Requirements**: Read `.clavix/outputs/[project]/full-prd.md`.
+3.  **Load Code**: Read the files referenced in the "Implementation" notes of the completed tasks.
 
-**What you'll see:**
-```
-Running tests...
-✅ All 23 tests passed
-
-Building code...
-✅ Clean build, no errors
+### Phase 2: The Audit (Comparison)
+Perform a **gap analysis**:
+*   **Plan vs. Code**: Did they use the library/pattern specified? (e.g., "Used `fetch` but Plan said `UserService`").
+*   **PRD vs. Code**: Is the business logic (validation, edge cases) present?
+*   **Code vs. Standards**: Are there hardcoded secrets? `any` types? Console logs?
 
-Checking code quality...
-✅ No linting issues
+### Phase 3: The Review Report
+Output a structured **Review Board**. Do not write a wall of text. Use the "Review Comment" format.
 
-Confidence: HIGH (I actually ran these)
-```
-
-#### Checks I Do With You
-
-Things I can analyze but need your input on:
-
-**Requirements Coverage:**
-- Did I build all the features you asked for?
-- Does the implementation match what you wanted?
-- Are there missing pieces?
-
-**User Experience:**
-- Does the interface work smoothly?
-- Are there console errors or warnings?
-- Does it feel right to use?
-
-**Integration & Performance:**
-- Do API calls work correctly?
-- Is performance acceptable?
-- Does it handle real-world data?
-
-**You'll see:**
-```
-Checking requirements coverage...
-Found all 5 requested features implemented.
-
-Does the login flow work as you expected? (yes/no)
-```
-
-#### Things You Tell Me
-
-Some things only you can verify:
-
-- Does it solve your original problem?
-- Are the business rules correct?
-- Do edge cases work properly?
-- Is it ready for production?
-- Is documentation good enough?
-
-### Understanding Your Results
-
-**What the symbols mean:**
-
-| Symbol | Status | What It Means |
-|--------|--------|---------------|
-| ✅ | Passed | This check is good |
-| ❌ | Failed | Needs fixing |
-| ⏭️ | Skipped | Check this later |
-| ➖ | N/A | Doesn't apply to your project |
-
-**Confidence levels:**
-- **HIGH** - I ran tests/commands, saw the results
-- **MEDIUM** - I analyzed code and got your confirmation
-- **LOW** - Based on what you told me
-
-**Example report:**
-```
-Verification Complete: User Authentication
-
-✅ AUTOMATED CHECKS
-   Tests: 23/23 passed
-   Build: Clean, no errors
-   Linting: No issues
-   Type Safety: All good
-
-⚠️  REQUIREMENTS COVERAGE
-   ✅ User registration works
-   ✅ Login/logout works
-   ❌ Password reset missing
-   ✅ Session management works
-
-📝 YOUR INPUT NEEDED
-   Business Logic: You confirmed it's correct
-   Ready for production: You said yes
-
-OVERALL: 85% - Ready with minor improvements
-STATUS: Address password reset before launch
-```
+#### Review Comment Categories
+*   🔴 **CRITICAL**: Architectural violation, security risk, or feature completely broken/missing. **Must fix.**
+*   🟠 **MAJOR**: Logic error, missing edge case handling, or deviation from PRD. **Should fix.**
+*   🟡 **MINOR**: Code style, naming, comments, or minor optimization. **Optional.**
+*   ⚪ **OUTDATED**: The code is correct, but the Plan/PRD was wrong. **Update Plan.**
 
 ---
 
-## When Things Fail
-
-### Don't Panic
-
-Failed checks are normal. They just tell you what needs work.
-
-**Critical issues (must fix before shipping):**
-- ❌ Tests failing
-- ❌ Code won't build
-- ❌ Type errors
-- ❌ Missing core features
-
-**Nice to fix (but not blockers):**
-- ⚠️ Linting warnings
-- ⚠️ Performance could be better
-- ⚠️ Documentation is thin
-- ⚠️ Edge cases need work
+## Output Format: The Review Board
 
-**When something fails, I'll:**
-1. Tell you exactly what's wrong
-2. Suggest how to fix it
-3. Offer to re-check after you make changes
-4. Point you to help if it's complex
+```markdown
+# Verification Report: [Phase Name / Feature]
 
-### Common Issues
+**Spec**: `tasks.md` (Phase X) | **Status**: [Pass/Fail/Warnings]
 
-**Example 1: Tests are failing**
-```
-❌ Tests failed: 3 of 23 integration tests
-
-Error: "User authentication endpoint not found"
-
-What to check:
-1. Are your auth routes set up correctly?
-2. Is the API endpoint configured right?
-3. Try running tests individually to see more details
-
-When you've fixed it: Just run /clavix:verify again
-```
-
-**Example 2: Missing features**
-```
-⚠️  Found 2 features from your requirements that aren't implemented:
-
-- Password reset functionality
-- Admin user management
-
-These were in your original requirements. Want to:
-- Build them now?
-- Remove them from requirements?
-- Ship without them for now?
-```
+## 🔍 Review Comments
 
-**Example 3: Performance concerns**
-```
-⚠️  Performance could be better:
+| ID | Severity | Location | Issue |
+|:--:|:--------:|:---------|:------|
+| #1 | 🔴 CRIT | `src/auth.ts` | **Architecture Violation**: Direct `axios` call used. Plan specified `apiClient` singleton. |
+| #2 | 🟠 MAJOR | `src/Login.tsx` | **Missing Req**: "Forgot Password" link missing (PRD 3.1). |
+| #3 | 🟡 MINOR | `src/Login.tsx` | **Hardcoded**: String "Welcome" should be in i18n/constants. |
 
-- Bundle size: 2.3MB (a bit large, recommended < 1MB)
-- Found some slow database queries
-- Page load: 4.2s (could be faster)
+## 🛠️ Recommended Actions
 
-These aren't blockers, but here's how to improve:
-- Split your code into smaller chunks
-- Optimize those database queries
-- Use lazy loading for heavy components
+- **Option A**: `Fix all critical` (Recommended)
+- **Option B**: `Fix #1 and #2`
+- **Option C**: `Mark #1 as outdated` (If you changed your mind about the architecture)
 ```
 
 ---
 
-## Extra Verification Options
-
-### Comprehensive Mode
-
-If you used `/clavix:improve --comprehensive` for your prompt, I'll do deeper checks:
-- More thorough edge case testing
-- Performance benchmarking
-- Security vulnerability scanning
-- Accessibility checks (WCAG compliance)
-- Cross-browser testing recommendations
-
-### Project-Specific Checks
-
-I adjust what I check based on what you're building:
-
-**Web Apps:**
-- Responsive design (works on mobile?)
-- Browser compatibility
-- Accessibility basics
-- SEO optimization
-
-**APIs:**
-- All endpoints working?
-- Auth/security correct?
-- Rate limiting in place?
-- API docs complete?
-
-**Mobile Apps:**
-- Platform guidelines followed?
-- Performance optimized?
-- Battery usage reasonable?
-- Ready for app store?
-
----
-
-## After Verification
+## Fixing Workflow (The Loop)
 
-### Everything Passed! 🎉
+When the user says "Fix #1" or "Fix all critical":
+1.  **Acknowledge**: "Fixing Review Comment #1..."
+2.  **Implement**: Modify the code to resolve the specific issue.
+3.  **Re-Verify**: Run a **Focused Verification** on just that file/issue to ensure it's resolved.
 
-When all checks pass, I'll tell you:
+----
 
-```
-All checks passed! Your implementation is solid.
-
-What would you like to do next?
-1. Archive this project with /clavix:archive
-2. Keep working on improvements
-3. Review specific items in detail
-```
-
-### Some Things Failed
-
-When there are issues, I'll be specific:
+## State Assertion (REQUIRED)
 
+**Before starting verification, output:**
 ```
-Found 2 things that need attention:
-
-❌ Password reset feature is missing
-❌ Loading states could be better
-
-What would you like to do?
-1. Fix these now (I can help)
-2. Fix them later
-3. Ship without them (if not critical)
-4. Archive anyway
+**CLAVIX MODE: Verification**
+Mode: verification
+Purpose: Spec-driven technical audit against requirements and implementation plan
+Implementation: BLOCKED - I'll analyze and report, not modify or fix
 ```
 
-### Want to Check Again?
-
-After you fix things:
-- Run `/clavix:verify` again for a full check
-- Or use `/clavix:verify --retry-failed` to just re-check what failed
-
-No rush! Fix things at your own pace.
-
----
+----
 
-## Workflow Navigation
-
-**You are here:** Verify (checking your work)
-
-**How you got here:**
-1. `/clavix:improve` → Made your prompt better
-2. `/clavix:implement` → Built what you needed
-3. **`/clavix:verify`** → Now checking it works (you are here)
-
-**What's next:**
-- Fix any issues → Run `/clavix:verify` again
-- Everything good → `/clavix:archive` to wrap up
-- Need help fixing → I can guide you
-
-**Related commands:**
-- `/clavix:implement` - Go back and fix issues
-- `/clavix:archive` - Archive when done
-- `/clavix:verify --retry-failed` - Just re-check what failed
-
----
-
-## Agent Transparency (v5.7.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
@@ -397,21 +148,7 @@ No rush! Fix things at your own pace.
 
 ---
 
-## Tips for Smooth Verification
-
-**Before you verify:**
-- Make sure you're actually done building
-- Run tests yourself first (quick sanity check)
-- Have your app running if I need to check the UI
-
-**During verification:**
-- Be honest - if something doesn't work, say so
-- Ask questions if a check doesn't make sense
-- It's okay to skip some checks and come back later
-
-**After verification:**
-- Fix critical stuff first (tests, builds, core features)
-- Use `--retry-failed` to just re-check what you fixed
-- Don't stress perfection - good enough is often good enough to ship
-
-**Remember:** I'm just checking, not judging. Failed checks help you ship better work!
+## Tips for the Agent
+*   **Be Strict**: You are the gatekeeper of quality. It's better to be annoying about an architectural violation now than to let technical debt slide.
+*   **Be Specific**: Never say "fix the code". Say "Import `apiClient` from `@/utils/api` and replace line 42."
+*   **Trust the Code**: If the code says `console.log`, and the plan says "No logs", that is a defect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.7.1",
+  "version": "5.8.0",
   "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation.\n\nSLASH COMMANDS (in your AI assistant):\n  /clavix:improve    Optimize prompts with auto-depth\n  /clavix:prd        Generate PRD through questions\n  /clavix:plan       Create task breakdown from PRD\n  /clavix:implement  Execute tasks with progress tracking\n  /clavix:start      Begin conversational session\n  /clavix:summarize  Extract requirements from conversation\n  /clavix:refine     Refine existing PRD or prompt\n  /clavix:verify     Verify implementation against requirements\n  /clavix:archive    Archive completed projects\n\nWorks with Claude Code, Cursor, Windsurf, and 20 AI coding tools.",
   "type": "module",
   "main": "dist/index.js",