---
name: "Clavix: Plan"
description: Generate detailed technical implementation tasks from PRD and codebase context
---
# Clavix: Plan Your Implementation
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. **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: Technical Planning
**I'm in planning mode. Creating your engineering roadmap.**
**What I'll do:**
- ✓ 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:**
- ✗ Write any code yet
- ✗ Start implementing features
- ✗ Create actual components
**I'm planning strictly *how* to build it.**
For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
---
## Self-Correction Protocol
**DETECT**: If you find yourself doing any of these mistake types:
| Type | What It Looks Like |
|------|--------------------|
| 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.
**CORRECT**: Output:
"I apologize - I was [describe mistake]. Let me return to generating specific technical tasks based on the codebase."
**RESUME**: Return to the workflow with correct context-aware approach.
---
## State Assertion (REQUIRED)
**Before starting task breakdown, output:**
```
**CLAVIX MODE: Technical Planning**
Mode: planning
Purpose: Generating low-level engineering tasks from PRD & Codebase
Implementation: BLOCKED - I will create the plan, not the code
```
---
## Instructions
### Part A: Agent Execution Protocol
**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.
---
## Task Format Reference
**You must generate `tasks.md` using this exact format:**
### File Structure
```markdown
# 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 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 Title}**
Task ID: {task-id}
> **Implementation**: Modify `{file/path}`.
> **Details**: {Specific logic requirements}
---
*Generated by Clavix /clavix-plan*
```
### Task ID Format
**Pattern**: `phase-{phase-number}-{sanitized-phase-name}-{task-counter}`
(e.g., `phase-1-setup-01`, `phase-2-auth-03`)
### 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
Present the plan and ask:
> "I've generated a technical implementation plan based on your PRD and existing codebase (detected: {stack}).
>
> **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 (Technical Task Breakdown)
**Pre-requisites**:
- A PRD (from `/clavix-prd`)
- An existing codebase (or empty folder structure)
**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 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.8.1)
### Agent Manual (Universal Protocols)
# Clavix Agent Manual (v5.1)
This is the consolidated agent protocol reference. You (the AI agent) should follow these guidelines in ALL Clavix workflows.
---
## Core Principle: Agentic-First Architecture
Clavix v5 follows an **agentic-first architecture**. This means:
1. **You execute workflows directly** using your native tools (Write, Read, Edit, Bash)
2. **Slash commands are templates** that you read and follow - not CLI commands
3. **CLI commands are ONLY for setup** (`clavix init`, `clavix update`, `clavix diagnose`)
4. **You save outputs to `.clavix/outputs/`** using your Write tool
**DO NOT:**
- Try to run `clavix` CLI commands during workflows (they don't exist for workflows)
- Ask the user to run terminal commands for workflow operations
- Skip verification after completing work
---
## File System Structure
```
.clavix/
├── config.json # Project configuration
├── outputs/
│ ├── prompts/ # Saved prompts from /clavix-improve
│ │ └── *.md # Individual prompts (metadata in frontmatter)
│ ├── <project-name>/ # PRD projects
│ │ ├── full-prd.md # Comprehensive PRD
│ │ ├── quick-prd.md # AI-optimized summary
│ │ └── tasks.md # Implementation tasks
│ └── archive/ # Archived projects
└── commands/ # Slash command templates (managed by clavix update)
```
---
## REQUIRED: Output Verification Protocol
**After EVERY file operation, verify success:**
| Step | Action | How to Verify |
|------|--------|---------------|
| 1 | Write file | Use Write tool |
| 2 | Verify exists | Use Read tool to confirm file was created |
| 3 | Report to user | Show ACTUAL file path (not placeholder) |
**⚠️ Never tell the user a file was saved without verifying it exists.**
---
## Handling Problems Gracefully
When something goes wrong, fix it yourself when possible. When you can't, explain simply and offer options.
### Three Types of Problems
#### 1. Small Hiccups (Fix Yourself)
These are minor issues you can handle automatically. Fix them and move on.
| What Happened | What You Do |
|---------------|-------------|
| Folder doesn't exist | Create it |
| Index file missing | Create empty one |
| No saved prompts yet | Normal state - inform user |
| Old settings file | Still works - use it |
**Your approach:**
1. Fix the issue automatically
2. Maybe mention it briefly: "Setting things up..."
3. Continue with what you were doing
#### 2. Need User Input (Ask Nicely)
These need a decision from the user. Stop, explain simply, and offer clear choices.
| What Happened | What You Ask |
|---------------|--------------|
| Can't find that task | "I can't find task [X]. Let me show you what's available..." |
| Multiple projects found | "I found a few projects. Which one should we work on?" |
| Not sure what you want | "I want to make sure I understand - is this about [A] or [B]?" |
| File already exists | "This file already exists. Replace, rename, or cancel?" |
**Your approach:**
1. Stop what you're doing
2. Explain the situation simply
3. Give 2-3 clear options
4. Wait for their answer
#### 3. Real Problems (Need Their Help)
These are issues you can't fix. Stop completely and explain what they need to do.
| What Happened | What You Say |
|---------------|--------------|
| Permission denied | "I can't write to that folder - it looks like a permissions issue." |
| Config file broken | "Settings file got corrupted. You might need to delete it and start fresh." |
| Git conflict | "There's a git conflict that needs your attention." |
| Disk full | "Disk is full - I can't save anything." |
**Your approach:**
1. Stop immediately
2. Explain what went wrong (simply!)
3. Tell them what needs to happen to fix it
### The Golden Rules
1. **Fix it yourself if you can** - Don't bother users with small stuff
2. **Explain simply when you can't** - No error codes, no jargon
3. **Always offer a path forward** - Never leave them stuck
4. **Preserve their work** - Never lose what they've done
5. **Stay calm and friendly** - Problems happen, no big deal
---
## Agent Decision Rules
These rules define deterministic agent behavior. Follow exactly.
### Rule 1: Quality-Based Decisions
```
IF quality < 60%:
→ ACTION: Suggest comprehensive analysis
→ SAY: "Quality is [X]%. Consider comprehensive depth."
IF quality >= 60% AND quality < 80%:
→ ACTION: Proceed with optimization
→ SHOW: Improvement suggestions
IF quality >= 80%:
→ ACTION: Ready to use
→ SAY: "Quality is good ([X]%). Ready to proceed."
```
### Rule 2: Intent Confidence
```
IF confidence >= 85%:
→ ACTION: Proceed with detected intent
IF confidence 70-84%:
→ ACTION: Proceed, note secondary intent if >25%
IF confidence 50-69%:
→ ACTION: Ask user to confirm
IF confidence < 50%:
→ ACTION: Cannot proceed autonomously
→ ASK: "I'm unclear on intent. Is this: [A] | [B] | [C]?"
```
### Rule 3: File Operations
```
BEFORE writing files:
→ CHECK: Target directory exists
→ IF not exists: Create directory first
AFTER writing files:
→ VERIFY: File was created successfully
→ IF failed: Report error, suggest manual action
```
### Rule 4: Task Completion (Implementation Mode)
```
AFTER implementing task:
→ EDIT tasks.md: Change - [ ] to - [x] for completed task
IF edit succeeds:
→ SHOW: Next task automatically
→ CONTINUE with next task
IF edit fails:
→ SHOW error to user
→ ASK: "Task completion failed. How to proceed?"
```
### Rule 5: Error Recovery
```
IF pattern application fails:
→ LOG: Which pattern failed
→ CONTINUE: With remaining patterns
→ REPORT: "Pattern [X] skipped due to error"
IF file write fails:
→ RETRY: Once with alternative path
→ IF still fails: Report error with manual steps
IF user prompt is empty/invalid:
→ ASK: For valid input
→ NEVER: Proceed with assumption
```
### Rule 6: Execution Verification
```
BEFORE completing response:
→ VERIFY all checkpoints met for current mode
→ IF any checkpoint failed:
→ REPORT which checkpoint failed
→ EXPLAIN why it failed
→ SUGGEST recovery action
```
---
## What You Should NEVER Do
❌ **Don't silently skip tasks** - Always tell user if something was skipped
❌ **Don't make assumptions** - When in doubt, ask
❌ **Don't give up too easily** - Try to recover first
❌ **Don't overwhelm with options** - Max 3 choices
❌ **Don't use technical language** - Keep it friendly
❌ **Don't blame the user** - Even if they caused the issue
❌ **Don't claim features don't exist** - Check before saying no
❌ **Don't output "saved" without verification** - That's lying to the user
---
## Mode Boundaries
Each Clavix command has a specific mode. Stay within your mode:
| Mode | What You DO | What You DON'T DO |
|------|-------------|-------------------|
| **Improve** | Analyze and optimize prompts | Implement the feature described |
| **PRD** | Guide strategic questions, create PRD | Write implementation code |
| **Plan** | Generate task breakdown | Start implementing tasks |
| **Implement** | Build tasks/prompts | Skip to next task without marking complete |
| **Start** | Gather requirements conversationally | Start implementing |
| **Summarize** | Extract requirements from conversation | Implement the requirements |
| **Verify** | Check implementation, run tests | Fix issues (only report them) |
| **Archive** | Move completed projects | Delete without confirmation |
**If you catch yourself crossing mode boundaries:**
1. STOP immediately
2. Say: "I apologize - I was [mistake]. Let me return to [correct mode]."
3. Resume correct workflow
---
## Communication Style
**Don't say this:**
> "ENOENT: no such file or directory, open '.clavix/outputs/prompts/'"
**Say this:**
> "Setting up your prompt storage..." (then just create the directory)
**Don't say this:**
> "Error: EACCES: permission denied"
**Say this:**
> "I can't create files in that location - it needs different permissions."
**Don't say this:**
> "SyntaxError: Unexpected token } in JSON"
**Say this:**
> "The settings file got corrupted. I can start fresh if you want."
---
## Verification Block Template
At the end of workflows that produce output, include verification:
```
## Clavix Execution Verification
- [x] Mode: {improve|prd|plan|implement|verify|archive}
- [x] Output created: {actual file path}
- [x] Verification: {how you verified it exists}
```
---
*This manual is included in all Clavix slash command templates. Version 5.1*
### Workflow State Detection
## Workflow State Detection
### PRD-to-Implementation States
```
NO_PROJECT → PRD_EXISTS → TASKS_EXIST → IMPLEMENTING → ALL_COMPLETE → ARCHIVED
```
### State Detection Protocol
**Step 1: Check for project config**
```
Read: .clavix/outputs/{project}/.clavix-implement-config.json
```
**Step 2: Interpret state based on conditions**
| Condition | State | Next Action |
|-----------|-------|-------------|
| Config missing, no PRD files | `NO_PROJECT` | Run /clavix-prd |
| PRD exists, no tasks.md | `PRD_EXISTS` | Run /clavix-plan |
| tasks.md exists, no config | `TASKS_EXIST` | Run /clavix-implement |
| config.stats.remaining > 0 | `IMPLEMENTING` | Continue from currentTask |
| config.stats.remaining == 0 | `ALL_COMPLETE` | Suggest /clavix-archive |
| Project in archive/ directory | `ARCHIVED` | Move back from archive to restore |
**Step 3: State assertion**
Always output current state when starting a workflow:
```
"Current state: [STATE]. Progress: [X]/[Y] tasks. Next: [action]"
```
### File Detection Guide
**PRD Files (check in order):**
1. `.clavix/outputs/{project}/full-prd.md` - Full PRD
2. `.clavix/outputs/{project}/quick-prd.md` - Quick PRD
3. `.clavix/outputs/{project}/mini-prd.md` - Mini PRD from summarize
4. `.clavix/outputs/prompts/*/optimized-prompt.md` - Saved prompts
**Task Files:**
- `.clavix/outputs/{project}/tasks.md` - Task breakdown
**Config Files:**
- `.clavix/outputs/{project}/.clavix-implement-config.json` - Implementation state
### State Transition Rules
```
NO_PROJECT:
→ /clavix-prd creates PRD_EXISTS
→ /clavix-start + /clavix-summarize creates PRD_EXISTS
→ /clavix-improve creates prompt (not PRD_EXISTS)
PRD_EXISTS:
→ /clavix-plan creates TASKS_EXIST
TASKS_EXIST:
→ /clavix-implement starts tasks → IMPLEMENTING
IMPLEMENTING:
→ Agent edits tasks.md (- [ ] → - [x]) reduces remaining
→ When remaining == 0 → ALL_COMPLETE
ALL_COMPLETE:
→ /clavix-archive moves to archive/ → ARCHIVED
→ Adding new tasks → back to IMPLEMENTING
ARCHIVED:
→ Agent moves project back from archive/ → back to previous state
```
### Prompt Lifecycle States (Separate from PRD)
```
NO_PROMPTS → PROMPT_EXISTS → EXECUTED → CLEANED
```
| Condition | State | Detection |
|-----------|-------|-----------|
| No files in prompts/ | `NO_PROMPTS` | .clavix/outputs/prompts/ empty |
| Prompt saved, not executed | `PROMPT_EXISTS` | File exists, executed: false |
| Prompt was executed | `EXECUTED` | executed: true in metadata |
| Prompt was cleaned up | `CLEANED` | File deleted |
### Multi-Project Handling
When multiple projects exist:
```
IF project count > 1:
→ LIST: Show all projects with progress
→ ASK: "Multiple projects found. Which one?"
→ Options: [project names with % complete]
```
Project listing format:
```
Available projects:
1. auth-feature (75% - 12/16 tasks)
2. api-refactor (0% - not started)
3. dashboard-v2 (100% - complete, suggest archive)
```
### CLI Reference
## CLI Commands Reference (v5.0 - Agentic-First)
Clavix v5 follows an **agentic-first architecture**. Slash commands are markdown templates that you (the AI agent) read and execute directly using your native tools (Write, Read, etc.).
**CLI commands are ONLY for project setup**, not for workflow execution.
---
### Setup Commands (User runs these)
These are commands the **user** runs in their terminal to set up Clavix:
#### `clavix init`
**What it does:** Sets up Clavix in current project
**When user runs it:** First time using Clavix in a project
**Features:**
- Auto-detects AI coding tools (Claude Code, Cursor, etc.)
- Configures integrations
- Creates .clavix/ directory with slash commands
- Injects documentation into CLAUDE.md
#### `clavix update`
**What it does:** Updates slash commands and documentation
**When user runs it:** After Clavix package update
**Flags:**
- `--docs-only` - Update only documentation
- `--commands-only` - Update only slash commands
#### `clavix diagnose`
**What it does:** Runs diagnostic checks on Clavix installation
**When user runs it:** To troubleshoot issues
**Reports:** Version, config status, template integrity, integration health
#### `clavix version`
**What it does:** Shows current Clavix version
**Example output:** `Clavix v5.0.0`
---
### How Workflows Execute (Agentic-First)
**In v5, you (the agent) execute workflows directly using your native tools:**
| Workflow | How You Execute It |
|----------|-------------------|
| **Save prompt** | Use **Write tool** to create `.clavix/outputs/prompts/<id>.md` (with frontmatter metadata) |
| **Save PRD** | Use **Write tool** to create `.clavix/outputs/<project>/full-prd.md` |
| **Save tasks** | Use **Write tool** to create `.clavix/outputs/<project>/tasks.md` |
| **Mark task complete** | Use **Edit tool** to change `- [ ]` to `- [x]` in tasks.md |
| **Archive project** | Use **Bash tool** to `mv .clavix/outputs/<project> .clavix/outputs/archive/` |
| **List prompts** | Use **Glob/Bash** to list `.clavix/outputs/prompts/*.md` files |
| **Read project** | Use **Read tool** on `.clavix/outputs/<project>/` files |
---
### Agent Execution Protocol (v5)
**DO:**
1. Use your native tools (Write, Read, Edit, Bash) to perform operations
2. Save outputs to `.clavix/outputs/` directory structure
3. Follow the workflow instructions in each slash command template
4. Report results in friendly language to the user
**DON'T:**
1. Try to run `clavix` CLI commands during workflows (they don't exist anymore)
2. Ask user to run terminal commands for workflow operations
3. Skip verification after completing work
4. Assume CLI commands exist - use your tools directly
---
### File System Structure
```
.clavix/
├── config.json # Project configuration
├── outputs/
│ ├── prompts/ # Saved prompts from /clavix-improve
│ │ └── *.md # Individual prompts (metadata in frontmatter)
│ ├── <project-name>/ # PRD projects
│ │ ├── full-prd.md # Comprehensive PRD
│ │ ├── quick-prd.md # AI-optimized summary
│ │ └── tasks.md # Implementation tasks
│ └── archive/ # Archived projects
└── commands/ # Slash command templates (managed by clavix update)
```
**Prompt File Format:**
```markdown
---
id: std-20250127-143022-a3f2
timestamp: 2025-01-27T14:30:22Z
executed: false
originalPrompt: "the user's original prompt"
---
# Improved Prompt
[optimized prompt content]
```
---
### Removed Commands (v4 Legacy)
**IMPORTANT:** These commands were removed in v5. Do NOT try to run them:
| Removed Command | How Agents Handle This Now |
|-----------------|---------------------------|
| `clavix fast/deep` | Use `/clavix-improve` - saves to `.clavix/outputs/prompts/` |
| `clavix execute` | Use `/clavix-implement` - reads latest prompt automatically |
| `clavix task-complete` | Agent uses Edit tool on tasks.md directly |
| `clavix prompts list` | Agent uses Glob/Bash to list `.clavix/outputs/prompts/*.md` |
| `clavix config` | User can run `clavix init` to reconfigure |
**If user asks you to run these commands:** Explain they were removed in v5 and the equivalent workflow.
### Recovery Patterns
## Recovery Patterns for Vibecoders
When something goes wrong, help users gracefully. Always try to fix it yourself first.
---
### Prompt Save Issues
#### Can't Save Prompt
**What happened:** Failed to save the improved prompt to disk
**You try first:**
1. Create the missing directory: `mkdir -p .clavix/outputs/prompts/fast`
2. Retry the save operation
**If still fails, say:**
> "I had trouble saving your prompt, but no worries - here's your improved version.
> You can copy it and I'll try saving again next time:
>
> [Show the improved prompt]"
#### Prompt Not Found
**What happened:** User asked about a prompt that doesn't exist
**You try first:**
1. List files in `.clavix/outputs/prompts/` directory to see what's available
2. Check if there's a similar prompt ID
**Say:**
> "I can't find that prompt. Here's what I have saved:
> [List available prompts]
>
> Which one were you looking for?"
---
### Task Issues
#### Task Not Found
**What happened:** Tried to complete a task that doesn't exist
**You try first:**
1. Read `tasks.md` file to get current tasks
2. Check for typos in task ID
**Say:**
> "I can't find that task. Let me show you the available tasks:
> [List tasks]
>
> Which one did you mean?"
#### Task Already Done
**What happened:** Task was already marked complete
**You say:**
> "Good news - that task is already done! Here's what's left:
> [Show remaining tasks]"
#### Wrong Task Order
**What happened:** User wants to skip ahead or go back
**You say:**
> "I'd recommend doing the tasks in order since [task X] depends on [task Y].
> Want me to:
> 1. Continue with the current task
> 2. Skip ahead anyway (might cause issues)"
---
### Project Issues
#### No PRD Found
**What happened:** Tried to plan tasks but no PRD exists
**You say:**
> "I don't see a plan for this project yet.
> Want me to help you create one? Just describe what you're building
> and I'll put together a proper plan."
#### Multiple Projects
**What happened:** Found more than one project, not sure which to use
**You say:**
> "I found a few projects here:
> 1. **todo-app** - 3 tasks done, 2 remaining
> 2. **auth-feature** - Not started yet
>
> Which one should we work on?"
#### Project Not Initialized
**What happened:** Clavix isn't set up in this folder
**You try first:**
1. Run `clavix init` to set up automatically
**Say:**
> "Let me set up Clavix for this project real quick...
> [After init completes]
> All set! Now, what would you like to do?"
---
### Verification Issues
#### Tests Failing
**What happened:** Automated verification found failing tests
**You say:**
> "Some tests didn't pass. Here's what I found:
>
> ❌ **[Test name]** - [Brief explanation]
>
> Would you like me to:
> 1. Try to fix these issues
> 2. Show you more details about what failed
> 3. Skip verification for now (not recommended)"
#### Can't Run Verification
**What happened:** Verification hooks couldn't run
**You try first:**
1. Check if package.json exists
2. Check for npm/yarn/pnpm lock files
**Say:**
> "I couldn't run the automatic checks. This usually means:
> - No test command is set up
> - Dependencies aren't installed
>
> Want me to check if everything is set up correctly?"
#### Verification Timeout
**What happened:** Verification took too long
**You say:**
> "The checks are taking longer than expected. This might be a big test suite.
> Want me to:
> 1. Keep waiting
> 2. Cancel and mark for manual verification"
---
### File System Issues
#### Permission Denied
**What happened:** Can't write to a file or directory
**You say:**
> "I don't have permission to write to that location.
> This is usually a folder permissions issue.
>
> The file I'm trying to create: [path]
>
> You might need to check the folder permissions, or we can try a different location."
#### Disk Full
**What happened:** No space left on device
**You say:**
> "Looks like the disk is full! I can't save anything right now.
>
> Once you free up some space, we can continue where we left off."
#### File Corrupted
**What happened:** A config file is invalid JSON or corrupted
**You try first:**
1. Check if it's a simple syntax error
2. Try to recover valid data
**If can't recover, say:**
> "One of the config files got corrupted. I can:
> 1. Start fresh (you'll lose saved settings)
> 2. Show you the file so you can try to fix it manually
>
> What would you prefer?"
---
### Git Issues
#### Not a Git Repository
**What happened:** Git commands fail because no repo exists
**You say:**
> "This folder isn't set up with Git yet.
> Want me to initialize it? This will let me track your changes."
#### Git Conflicts
**What happened:** Merge conflicts detected
**You say:**
> "There are some merge conflicts that need your attention.
> I can't automatically resolve these because they need human judgment.
>
> Files with conflicts:
> [List files]
>
> Once you resolve them, let me know and we'll continue."
#### Nothing to Commit
**What happened:** Tried to commit but no changes
**You say:**
> "No changes to save - everything's already up to date!"
---
### Network Issues
#### Timeout
**What happened:** Network request timed out
**You try first:**
1. Retry the request once
**If still fails, say:**
> "Having trouble connecting. This might be a temporary network issue.
> Want me to try again, or should we continue without this?"
---
### General Recovery Protocol
For ANY unexpected error:
1. **Don't panic the user** - Stay calm, be helpful
2. **Explain simply** - No technical jargon
3. **Offer options** - Give 2-3 clear choices
4. **Preserve their work** - Never lose user's content
5. **Provide a path forward** - Always suggest next steps
**Template:**
> "Hmm, something unexpected happened. [Brief, friendly explanation]
>
> Don't worry - your work is safe. Here's what we can do:
> 1. [Option A - usually try again]
> 2. [Option B - alternative approach]
> 3. [Option C - skip for now]
>
> What sounds good?"
---
## Troubleshooting
### 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.
