clavix 2.5.0 → 2.6.0

package/README.md

@@ -25,13 +25,28 @@ Clavix is built on CLEAR (Concise, Logical, Explicit, Adaptive, Reflective), an
 Provider paths and argument placeholders are listed in [docs/providers.md](docs/providers.md).
 
 ## Quickstart
+
+### For AI Agents (Recommended)
+
+Most Clavix users work through AI coding assistants:
+
 ```bash
+# 1. Initialize in your project
 npm install -g clavix
-# or without a global install
-npx clavix@latest init
+clavix init
+
+# 2. Use slash commands in your AI agent
+/clavix:fast "Create a login page"
+/clavix:deep "Build an API for user management"
+/clavix:prd  # Full PRD workflow
 ```
 
-Common commands:
+**Supported agents**: Claude Code, Cursor, Windsurf, and [20+ more providers](docs/providers.md)
+
+### Direct CLI Usage (Alternative)
+
+You can also use Clavix directly from the terminal:
+
 ```bash
 clavix init
 clavix fast "Create a login page"
@@ -39,6 +54,8 @@ clavix deep "Build an API for user management"
 clavix prd
 ```
 
+**Note**: CLI usage is primarily for initialization and state management. AI agents handle the workflow orchestration via slash commands.
+
 ## Full documentation
 - Overview & navigation: [docs/index.md](docs/index.md)
 - Command reference: [docs/commands/](docs/commands/README.md)

package/dist/cli/commands/implement.js

@@ -41,6 +41,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const task_manager_1 = require("../../core/task-manager");
 const git_manager_1 = require("../../core/git-manager");
+const agent_error_messages_1 = require("../../utils/agent-error-messages");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs-extra"));
 class Implement extends core_1.Command {
@@ -67,7 +68,8 @@ class Implement extends core_1.Command {
                 const prdPath = await manager.findPrdDirectory(flags.project);
                 tasksPath = path.join(prdPath, 'tasks.md');
                 if (!(await fs.pathExists(tasksPath))) {
-                    this.error('No tasks.md found\n\nHint: Run "clavix plan" first to generate task breakdown');
+                    const projectName = flags.project || path.basename(path.dirname(tasksPath));
+                    this.error(agent_error_messages_1.AgentErrorMessages.noTasksFound(projectName));
                 }
                 console.log(chalk_1.default.dim(`Found: ${tasksPath}\n`));
             }
@@ -232,7 +234,7 @@ class Implement extends core_1.Command {
         }
         // No PRD projects found
         if (prdProjects.length === 0) {
-            this.error('No PRD projects found in .clavix/outputs/\n\nHint: Create a PRD first using: clavix prd');
+            this.error(agent_error_messages_1.AgentErrorMessages.noPrdFound());
         }
         // Only one PRD - auto-select
         if (prdProjects.length === 1) {

package/dist/cli/commands/plan.js

@@ -45,6 +45,7 @@ const task_manager_1 = require("../../core/task-manager");
 const session_manager_1 = require("../../core/session-manager");
 const conversation_analyzer_1 = require("../../core/conversation-analyzer");
 const file_system_1 = require("../../utils/file-system");
+const agent_error_messages_1 = require("../../utils/agent-error-messages");
 class Plan extends core_1.Command {
     async run() {
         const { flags } = await this.parse(Plan);
@@ -69,11 +70,7 @@ class Plan extends core_1.Command {
             if (!prdPath) {
                 selectedProject = await this.resolveProjectDirectory(manager, flags.project);
                 if (!selectedProject) {
-                    this.error('No PRD projects found in .clavix/outputs/\n\n' +
-                        'Hints:\n' +
-                        '  • Run "clavix prd" to generate a PRD\n' +
-                        '  • Run "clavix summarize" to create a mini-PRD\n' +
-                        '  • Use "clavix plan --session <id>" to plan from a session');
+                    this.error(agent_error_messages_1.AgentErrorMessages.noPrdFound());
                 }
                 prdPath = selectedProject.path;
                 projectName = selectedProject.name;
@@ -93,11 +90,7 @@ class Plan extends core_1.Command {
             console.log(chalk_1.default.dim('Looking for PRD artifacts...'));
             const availableSources = await manager.detectAvailableSources(prdPath);
             if (availableSources.length === 0) {
-                this.error('No PRD artifacts found in this directory\n\n' +
-                    'Hints:\n' +
-                    '  • Generate a PRD with: clavix prd\n' +
-                    '  • Create a mini-PRD with: clavix summarize\n' +
-                    '  • Plan from a session with: clavix plan --session <id>');
+                this.error(agent_error_messages_1.AgentErrorMessages.noPrdFound());
             }
             if (sourcePreference !== 'auto' && !availableSources.includes(sourcePreference)) {
                 this.error(`Preferred source "${sourcePreference}" not found in ${prdPath}\n\n` +

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

@@ -5,49 +5,83 @@ description: Archive completed PRD projects
 
 # Clavix Archive - PRD Project Archival
 
+> **⚠️ Agent Execution Note**: This command requires CLI execution. AI agents should run `clavix archive` via Bash tool to perform archival operations. Direct file manipulation is not recommended due to state tracking complexity.
+
 You are helping the user archive completed PRD projects to keep their workspace organized.
 
 ## Instructions
 
-1. **Understanding Archive**:
-   - Archives move completed PRD projects from `.clavix/outputs/` to `.clavix/outputs/archive/`
-   - Archived projects are no longer shown in active project lists
-   - Projects can be restored from archive if needed
-   - Only projects with all tasks completed should typically be archived
+### Part A: Agent Execution Protocol
+
+**As an AI agent, you should:**
+
+1. **Run the CLI command** to handle archival operations:
+   ```bash
+   clavix archive
+   ```
+
+   The CLI will:
+   - Prompt user for project selection
+   - Validate task completion status
+   - Handle file operations safely
+   - Update state tracking
 
-2. **Interactive Archive Mode**:
+2. **Choose the appropriate mode** based on user intent:
+
+   - **Interactive mode** (no arguments): User selects from list
+   - **Specific project**: `clavix archive [project-name]`
+   - **Force archive incomplete**: `clavix archive [project-name] --force`
+   - **Permanent delete**: `clavix archive [project-name] --delete`
+   - **List archived**: `clavix archive --list`
+   - **Restore**: `clavix archive --restore [project-name]`
+
+3. **Before running the command**, validate:
+   - Check if `.clavix/outputs/` directory exists
+   - Verify user intent (archive vs delete vs restore)
+   - Confirm project name if specified
+
+4. **After CLI completes**, communicate results:
+   - Confirm where project was moved
+   - Mention restoration is possible (unless deleted)
+   - Update user on next steps
+
+### Part B: Understanding Archive Operations
+
+**Archive Modes**:
+
+1. **Interactive Archive Mode**:
    ```bash
    clavix archive
    ```
 
-   This will:
-   - List all PRD projects with 100% tasks completed
-   - Allow user to select which project to archive
-   - Confirm before archiving
-   - Move the project to archive directory
+   CLI behavior:
+   - Lists all PRD projects with 100% tasks completed
+   - Allows user to select which project to archive
+   - Confirms before archiving
+   - Moves the project to archive directory
 
-3. **Archive Specific Project**:
+2. **Archive Specific Project**:
    ```bash
    clavix archive [project-name]
    ```
 
-   This will:
-   - Check task completion status
-   - Warn if tasks are incomplete
-   - Ask for confirmation
-   - Archive the specific project
+   CLI behavior:
+   - Checks task completion status
+   - Warns if tasks are incomplete
+   - Asks for confirmation
+   - Archives the specific project
 
-4. **Force Archive (Incomplete Tasks)**:
+3. **Force Archive (Incomplete Tasks)**:
    ```bash
    clavix archive [project-name] --force
    ```
 
-   Use this when:
+   Use when:
    - Project scope changed and some tasks are no longer relevant
    - User wants to archive work-in-progress
    - Tasks are incomplete but project is done
 
-5. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION**
+4. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION**
    ```bash
    clavix archive [project-name] --delete
    ```
@@ -73,7 +107,7 @@ You are helping the user archive completed PRD projects to keep their workspace
    - Warns about permanent deletion
    - Lists what will be permanently deleted
 
-6. **List Archived Projects**:
+5. **List Archived Projects**:
    ```bash
    clavix archive --list
    ```
@@ -184,33 +218,53 @@ Result: Project permanently deleted from .clavix/outputs/api-experiment-1/
 
 When user mentions archiving or cleaning up projects:
 
-1. **Check completion status first**:
-   - Run `clavix archive` to see archivable projects
-   - Review task completion percentages
-   - Suggest archiving only completed projects
-
-2. **Confirm before archiving**:
-   - Always confirm which project to archive
-   - Mention the archive location
-   - Explain that it can be restored
-
-3. **Use --force cautiously**:
+1. **Validate prerequisites before running CLI**:
+   - Check if `.clavix/outputs/` directory exists
+   - If not, inform user no projects exist to archive
+   - Verify user intent (list, archive, restore, delete)
+
+2. **Check completion status first**:
+   - Run `clavix archive` (interactive mode) to see archivable projects
+   - CLI will display projects with completion percentages
+   - Review output and communicate options to user
+
+3. **Execute the appropriate command**:
+   - **Interactive selection**: `clavix archive` (let user pick from list)
+   - **Specific project**: `clavix archive [project-name]`
+   - **Force incomplete**: `clavix archive [project-name] --force`
+   - **List archived**: `clavix archive --list`
+   - **Restore**: `clavix archive --restore [project-name]`
+   - **Delete**: `clavix archive [project-name] --delete` (with extra caution)
+
+4. **Confirm before archiving**:
+   - If using specific project mode, confirm project name with user
+   - Mention the archive location (`.clavix/outputs/archive/`)
+   - Explain that restoration is possible
+
+5. **Use --force cautiously**:
    - Only when user explicitly wants to archive incomplete work
-   - Explain which tasks will remain incomplete
-   - Confirm they won't lose data (just moving location)
+   - Run command and let CLI show incomplete task count
+   - CLI will ask for user confirmation
+   - Explain they won't lose data (just moving location)
 
-4. **Suggest restoration**:
-   - If user mentions old work, check archive
-   - Use `clavix archive --list` to show what's archived
-   - Offer to restore if needed
+6. **Suggest restoration when appropriate**:
+   - If user mentions old/past work, check archive first
+   - Run `clavix archive --list` to show what's archived
+   - Offer to restore if needed via `clavix archive --restore [project]`
 
-5. **Handle delete requests carefully**:
-   - Always ask if they want to delete or archive
+7. **Handle delete requests with extreme caution**:
+   - Always ask: "Do you want to DELETE (permanent) or ARCHIVE (safe)?"
    - Explain that delete is permanent and irreversible
    - Suggest archive as the safer default
    - Use decision tree to help user decide
-   - Only proceed with `--delete` after clear confirmation
-   - Double-check it's truly no-value content (failed experiments, duplicates)
+   - Only run `--delete` after clear confirmation from user
+   - Double-check it's truly no-value content (failed experiments, duplicates, test data)
+   - CLI will require typing project name to confirm - this is expected
+
+8. **After CLI execution**:
+   - Communicate success/failure clearly
+   - Mention next steps (e.g., "Project archived, you can restore with `/clavix:archive --restore`")
+   - If error occurs, explain and suggest recovery options
 
 ## Workflow Navigation
 
@@ -238,54 +292,96 @@ When user mentions archiving or cleaning up projects:
 
 ### Issue: No projects available to archive
 **Cause**: No projects in `.clavix/outputs/` OR all already archived
-**Solution**:
-- Run `clavix archive --list` to see archived projects
-- Check `.clavix/outputs/` for active projects
-- If none exist, no action needed
+
+**Agent recovery**:
+1. Check if `.clavix/outputs/` exists: `ls .clavix/outputs/`
+2. If directory doesn't exist: "No PRD projects found. Create one with `/clavix:prd`"
+3. If empty: Run `clavix archive --list` to show archived projects
+4. Communicate: "All projects are already archived" or "No projects exist yet"
 
 ### Issue: Trying to archive project with incomplete tasks
 **Cause**: User wants to archive but tasks aren't 100% done
-**Solution** (inline):
-- Warn: "Project has X incomplete tasks. Archive anyway?"
-- Show which tasks are incomplete
-- Suggest `--force` flag if user confirms
-- Recommend completing tasks first if they're actually unfinished (not scope-changed)
+
+**Agent recovery**:
+1. CLI will warn about incomplete tasks
+2. Ask user: "Project has X incomplete tasks. Do you want to:
+   - Complete tasks first with `/clavix:implement`
+   - Archive anyway with `--force` (tasks remain incomplete but archived)
+   - Cancel archival"
+3. If user confirms force: Run `clavix archive [project] --force`
+4. If scope changed: Explain `--force` is appropriate
 
 ### Issue: Cannot restore archived project (name conflict)
 **Cause**: Project with same name already exists in active outputs
-**Solution**:
-- Error: "Project '[name]' already exists in active outputs"
-- Suggest renaming one of them
-- Or archive the active one first, then restore
-- Or restore to different name (if CLI supports it)
+
+**Agent recovery**:
+1. CLI will show error: "Project '[name]' already exists in active outputs"
+2. Ask user which option:
+   - Archive the active project first, then restore old one
+   - Keep both (manual rename required)
+   - Cancel restoration
+3. Execute user's choice
 
 ### Issue: Unsure whether to delete or archive
 **Cause**: User wants to clean up but uncertain about permanence
-**Solution**:
-- Use the decision tree in template
-- Default recommendation: ARCHIVE (safer)
-- Only suggest delete for: duplicates, failed experiments, test data
-- Remind: Archive is free, disk space is cheap, regret is expensive
+
+**Agent recovery**:
+1. Use decision tree to guide user:
+   ```
+   Ask user questions:
+   - "Is this a failed experiment with no learning value?"
+   - "Might you need to reference this code later?"
+   - "Are you unsure if it's valuable?"
+   ```
+2. Default recommendation: **ARCHIVE** (safer, reversible)
+3. Only suggest DELETE for: duplicates, failed experiments, test data with zero value
+4. Remind: "Archive is free, disk space is cheap, regret is expensive"
+
+### Issue: CLI command fails or hangs
+**Cause**: File system permissions, missing directory, or process error
+
+**Agent recovery**:
+1. Check error output from CLI
+2. Common fixes:
+   - Check `.clavix/outputs/` exists and is writable
+   - Verify project name is correct (no typos)
+   - Check if another process is accessing the files
+3. Suggest: Run with full project path or retry
+4. If persistent: Inform user to check file permissions
 
 ### Issue: Accidentally deleted project (used --delete instead of archive)
 **Cause**: User error or misunderstanding of --delete flag
-**Solution**:
-- Cannot be recovered from Clavix
-- Check if git history exists (if code was committed)
-- Check if user has backups
-- Learn: Use archive by default, delete only when absolutely certain
+
+**Agent recovery**:
+1. Acknowledge: "Project was permanently deleted via `--delete` flag"
+2. Check recovery options:
+   - "If code was committed to git, we can recover from git history"
+   - "Check if you have local backups"
+   - "Check if IDE has local history (VS Code, JetBrains)"
+3. Prevention: "Going forward, use ARCHIVE by default. Only DELETE when absolutely certain."
+4. No recovery possible from Clavix itself
 
 ### Issue: Archive directory getting too large
 **Cause**: Many archived projects accumulating
-**Solution**:
-- Archive is meant to grow - this is normal
-- Projects in archive don't affect performance
-- If truly concerned: Review archive, delete ancient/irrelevant projects
-- Or move very old archives to external backup storage
+
+**Agent response**:
+1. Explain: "Archive is designed to grow - this is normal behavior"
+2. Archived projects don't affect active command performance
+3. If user truly concerned:
+   - Review archive: `clavix archive --list`
+   - Identify ancient/irrelevant projects
+   - Delete only truly obsolete ones: `clavix archive [old-project] --delete`
+   - Or suggest external backup for very old projects
 
 ### Issue: Archived project but forgot what it was about
 **Cause**: No naming convention or time passed
-**Solution**:
-- Read PRD in archived project: `.clavix/outputs/archive/[project]/full-prd.md`
-- PRD contains problem, goal, and features
-- Consider better naming conventions: date-feature format (e.g., "2024-01-user-auth")
+
+**Agent recovery**:
+1. Read the PRD to remind user:
+   ```bash
+   cat .clavix/outputs/archive/[project-name]/full-prd.md
+   ```
+2. Summarize: Problem, Goal, Features from PRD
+3. Suggest: Better naming conventions going forward
+   - Example: `2024-01-user-auth` (date-feature format)
+   - Example: `ecommerce-checkout-v2` (project-component format)

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

@@ -9,23 +9,24 @@ You are helping the user implement tasks from their task plan with AI assistance
 
 ## Instructions
 
-1. **Run the implement command**:
-   ```bash
-   clavix implement
-   ```
-
-   This will:
-   - Show interactive PRD selection (if multiple projects exist)
-   - Locate the `tasks.md` file for the selected/specified project
-   - Show current progress
-   - Display the next incomplete task
-   - Prompt for git auto-commit preferences
-   - Create a config file for the AI agent
-
-   **Note**: You can skip the selection menu by specifying a project:
-   ```bash
-   clavix implement --project my-feature
-   ```
+1. **First-time setup - Run CLI command if needed**:
+
+   Check if `.clavix-implement-config.json` exists in the PRD output folder.
+
+   **If config file does NOT exist** (first time running implement):
+   - Run the CLI command to initialize:
+     ```bash
+     clavix implement
+     ```
+   - This will:
+     - Show current progress
+     - Display the next incomplete task
+     - Prompt user for git auto-commit preferences
+     - Create `.clavix-implement-config.json` file
+   - Wait for command to complete, then proceed with step 2
+
+   **If config file already exists**:
+   - Skip to step 2 (implementation loop)
 
 2. **As the AI agent, you should**:
 

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

@@ -9,14 +9,18 @@ You are helping the user generate a CLEAR-optimized implementation task breakdow
 
 ## Instructions
 
-### Part A: Procedural Steps (CLI Commands)
+### Part A: Agent Execution Protocol
 
-1. **Locate the PRD outputs**:
-   - Look for the most recent artifacts in `.clavix/outputs/[project-name]/`
-   - Accepted sources: `full-prd.md`, `quick-prd.md`, `mini-prd.md`, or `optimized-prompt.md`
+**As an AI agent, you have two execution options:**
+
+#### **Option 1: Run CLI Command** (Recommended for most cases)
+
+1. **Validate prerequisites**:
+   - Check if `.clavix/outputs/` directory exists
+   - Look for PRD artifacts: `full-prd.md`, `quick-prd.md`, `mini-prd.md`, or `optimized-prompt.md`
    - **If not found**: Error inline - "No PRD found in `.clavix/outputs/`. Use `/clavix:prd` or `/clavix:summarize` first."
 
-2. **Run the plan command**:
+2. **Run the CLI command**:
    ```bash
    clavix plan
    ```
@@ -26,12 +30,27 @@ You are helping the user generate a CLEAR-optimized implementation task breakdow
    clavix plan --project project-name
    ```
 
-   Or generate tasks directly from a saved session (auto-creates mini-prd.md):
+   Or generate from saved session (auto-creates mini-prd.md):
    ```bash
    clavix plan --session SESSION_ID
    ```
 
-   The CLI will prompt you to pick a project when multiple outputs are available.
+3. **CLI will handle**:
+   - Project selection (if multiple)
+   - Reading PRD content
+   - Generating task breakdown
+   - Creating `tasks.md` file
+   - Formatting with proper task IDs
+
+#### **Option 2: 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)
 
@@ -89,19 +108,103 @@ The generated `tasks.md` will look like:
 ---
 
 ## 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
 
 ---
 
 *Generated by Clavix /clavix:plan*
 ```
 
+## Task Format Reference (For Agent-Direct Generation)
+
+**If you're generating tasks directly (Option 2), follow this exact format:**
+
+### File Structure
+```markdown
+# Implementation Tasks
+
+**Project**: {project-name}
+**Generated**: {ISO timestamp}
+
+---
+
+## Phase {number}: {Phase Name}
+
+- [ ] {Task description} (ref: {PRD Section})
+  Task ID: {task-id}
+
+## Phase {number}: {Next Phase}
+
+- [ ] {Task description}
+  Task ID: {task-id}
+
+---
+
+*Generated by Clavix /clavix:plan*
+```
+
+### Task ID Format
+
+**Pattern**: `phase-{phase-number}-{sanitized-phase-name}-{task-counter}`
+
+**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})`
+
+**Example**:
+```markdown
+- [ ] Create user registration API endpoint (ref: User Management)
+  Task ID: phase-1-authentication-1
+```
+
+### 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
+
 ## Workflow Navigation
 
 **You are here:** Plan (Task Breakdown)
@@ -129,45 +232,98 @@ The generated `tasks.md` will look like:
 
 ### Issue: No PRD found in `.clavix/outputs/`
 **Cause**: User hasn't generated a PRD yet
-**Solution** (inline - already in template):
-- Show error: "No PRD found in `.clavix/outputs/`"
-- Suggest: "Use `/clavix:prd` or `/clavix:summarize` to generate one first"
-- Do not proceed with plan generation
+
+**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`"
+     - "Or use `clavix plan --session <id>` if you have a saved session"
+3. Do NOT proceed with plan generation without PRD
 
 ### Issue: Generated tasks are too granular (100+ tasks)
 **Cause**: Over-decomposition or large project scope
-**Solution**:
-- Group related micro-tasks into larger atomic tasks
-- Each task should be 15-60 minutes, not 5 minutes
-- Combine setup/configuration tasks
-- Suggest breaking project into multiple PRDs if truly massive
+
+**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
-**Solution**:
-- Review PRD - if vague, regenerate with more detail
-- Break each high-level task into 3-5 concrete sub-tasks
-- Each task should have a clear, testable deliverable
+
+**Agent recovery**:
+1. Read the PRD to assess detail level
+2. If PRD is vague:
+   - Suggest: "Let's improve the PRD with `/clavix:deep` 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
-**Solution**:
-- Manually reorder in tasks.md (database before API, API before UI)
-- Follow CLEAR [L] Logic principle: ensure sequential coherence
-- Group by technical layers or feature completion
+**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 CLEAR [L] Logic principle: ensure sequential coherence
 
 ### Issue: Tasks conflict with PRD or duplicate work
 **Cause**: Misinterpretation of PRD or redundant task generation
-**Solution**:
-- Review PRD and tasks side-by-side
-- Remove duplicate tasks
-- Align tasks with PRD requirements
-- Use `--overwrite` to regenerate after PRD clarification
+
+**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
-**Solution**:
-- Check if tasks.md has progress (any [x] checkboxes)
-- If no progress: Safe to use `--overwrite`
-- If progress exists: Review carefully before overwriting
-- Consider manual edits instead of full regeneration
+
+**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

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

@@ -97,7 +97,7 @@ You are helping the user create a Product Requirements Document (PRD) using Clav
    [Out of scope and additional context from Q4+Q5]
    ```
 
-3. Save both documents to `.clavix/outputs/[project-name]/`
+3. **Save both documents** using the file-saving protocol below
 
 4. **CLEAR Framework Validation** (automatic):
    - After PRD generation, the quick-prd.md is analyzed using CLEAR framework
@@ -107,6 +107,115 @@ You are helping the user create a Product Requirements Document (PRD) using Clav
 
 5. Display file paths, CLEAR validation results, and suggest next steps.
 
+## File-Saving Protocol (For AI Agents)
+
+**As an AI agent, follow these exact steps to save PRD files:**
+
+### Step 1: Determine Project Name
+- **From user input**: Use project name mentioned during Q&A
+- **If not specified**: Derive from problem/goal (sanitize: lowercase, spaces→hyphens, remove special chars)
+- **Example**: "Sales Manager Dashboard" → `sales-manager-dashboard`
+
+### Step 2: Create Output Directory
+```bash
+mkdir -p .clavix/outputs/{sanitized-project-name}
+```
+
+**Handle errors**:
+- If directory creation fails: Check write permissions
+- If `.clavix/` doesn't exist: Create it first: `mkdir -p .clavix/outputs/{project}`
+
+### Step 3: Save Full PRD
+**File path**: `.clavix/outputs/{project-name}/full-prd.md`
+
+**Content structure**:
+```markdown
+# Product Requirements Document: {Project Name}
+
+## Problem & Goal
+{User's Q1 answer - problem and goal}
+
+## Requirements
+### Must-Have Features
+{User's Q2 answer - expanded with details from conversation}
+
+### Technical Requirements
+{User's Q3 answer - tech stack, integrations, constraints}
+
+## Out of Scope
+{User's Q4 answer - explicit exclusions}
+
+## Additional Context
+{User's Q5 answer if provided, or omit section}
+
+---
+
+*Generated by Clavix /clavix:prd*
+*Generated: {ISO timestamp}*
+```
+
+### Step 4: Save Quick PRD
+**File path**: `.clavix/outputs/{project-name}/quick-prd.md`
+
+**Content structure** (2-3 paragraphs, AI-optimized):
+```markdown
+# {Project Name} - Quick PRD
+
+{Paragraph 1: Combine problem + goal + must-have features from Q1+Q2}
+
+{Paragraph 2: Technical requirements and constraints from Q3}
+
+{Paragraph 3: Out of scope and additional context from Q4+Q5}
+
+---
+
+*Generated by Clavix /clavix:prd*
+*Generated: {ISO timestamp}*
+```
+
+### Step 5: Verify Files Were Created
+```bash
+ls .clavix/outputs/{project-name}/
+```
+
+**Expected output**:
+- `full-prd.md`
+- `quick-prd.md`
+
+### Step 6: Communicate Success
+Display to user:
+```
+✓ PRD generated successfully!
+
+Files saved:
+  • Full PRD: .clavix/outputs/{project-name}/full-prd.md
+  • Quick PRD: .clavix/outputs/{project-name}/quick-prd.md
+
+CLEAR Validation Results:
+  [C] Conciseness: {score}/10 - {feedback}
+  [L] Logic: {score}/10 - {feedback}
+  [E] Explicitness: {score}/10 - {feedback}
+
+Next steps:
+  • Review and edit PRD files if needed
+  • Run /clavix:plan to generate implementation tasks
+```
+
+### Error Handling
+
+**If file write fails**:
+1. Check error message
+2. Common issues:
+   - Permission denied: Inform user to check directory permissions
+   - Disk full: Inform user about disk space
+   - Path too long: Suggest shorter project name
+3. Do NOT proceed to next steps without successful file save
+
+**If directory already exists**:
+- This is OK - proceed with writing files
+- Existing files will be overwritten (user initiated PRD generation)
+- If unsure: Ask user "Project `{name}` already exists. Overwrite PRD files?"
+
 ## CLEAR Validation
 
 **What gets validated:**

package/dist/utils/agent-error-messages.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Error messages optimized for AI agent consumption
+ *
+ * All messages follow these principles:
+ * - Programmatically actionable (no "ask user to..." language)
+ * - List recovery options explicitly
+ * - Provide context for decision-making
+ * - Avoid conversational tone in favor of structured guidance
+ */
+export declare class AgentErrorMessages {
+    /**
+     * Error: No PRD artifacts found in .clavix/outputs/
+     * Used by: plan.ts, implement.ts
+     */
+    static noPrdFound(): string;
+    /**
+     * Error: No tasks.md found for specified project
+     * Used by: implement.ts
+     */
+    static noTasksFound(projectName: string): string;
+    /**
+     * Error: .clavix-implement-config.json not found
+     * Used by: task-complete.ts, implement workflow
+     */
+    static configNotFound(): string;
+    /**
+     * Error: Specified task ID not found in tasks.md
+     * Used by: task-complete.ts
+     */
+    static taskNotFound(taskId: string, availableTasks: Array<{
+        id: string;
+        description: string;
+        completed: boolean;
+    }>): string;
+    /**
+     * Error: Archive validation failed (prerequisites not met)
+     * Used by: archive.ts
+     */
+    static archiveValidationFailed(reason: string): string;
+    /**
+     * Error: File operation failed (write, read, move, delete)
+     * Used by: Multiple commands performing file operations
+     */
+    static fileOperationFailed(operation: 'read' | 'write' | 'move' | 'delete', path: string, error?: string): string;
+    /**
+     * Error: Multiple PRD projects found, need user selection
+     * Used by: plan.ts, implement.ts when --project not specified
+     */
+    static multiplePrdsFound(projects: string[]): string;
+    /**
+     * Error: tasks.md already exists with progress
+     * Used by: plan.ts when generating tasks
+     */
+    static tasksExistWithProgress(completedCount: number, totalCount: number): string;
+    /**
+     * Error: Git repository not initialized
+     * Used by: implement.ts, task-complete.ts when git features expected
+     */
+    static gitNotInitialized(): string;
+    /**
+     * Error: No archivable projects found
+     * Used by: archive.ts
+     */
+    static noArchivableProjects(): string;
+    /**
+     * Error: Restoration failed due to name conflict
+     * Used by: archive.ts --restore
+     */
+    static restoreConflict(projectName: string): string;
+    /**
+     * Error: CLI command execution failed
+     * Used by: When running CLI commands via Bash tool
+     */
+    static cliExecutionFailed(command: string, exitCode: number, stderr?: string): string;
+    /**
+     * Error: Invalid task ID format
+     * Used by: task-complete.ts
+     */
+    static invalidTaskIdFormat(taskId: string): string;
+    /**
+     * Error: Session not found
+     * Used by: Commands using --session flag
+     */
+    static sessionNotFound(sessionId: string): string;
+    /**
+     * Warning: Task already completed
+     * Used by: task-complete.ts when marking already-done task
+     */
+    static taskAlreadyCompleted(taskId: string): string;
+}
+//# sourceMappingURL=agent-error-messages.d.ts.map

package/dist/utils/agent-error-messages.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Error messages optimized for AI agent consumption
+ *
+ * All messages follow these principles:
+ * - Programmatically actionable (no "ask user to..." language)
+ * - List recovery options explicitly
+ * - Provide context for decision-making
+ * - Avoid conversational tone in favor of structured guidance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentErrorMessages = void 0;
+class AgentErrorMessages {
+    /**
+     * Error: No PRD artifacts found in .clavix/outputs/
+     * Used by: plan.ts, implement.ts
+     */
+    static noPrdFound() {
+        return ('No PRD artifacts found in .clavix/outputs/\n\n' +
+            'Agent recovery options:\n' +
+            '  1. Execute /clavix:prd to generate comprehensive PRD\n' +
+            '  2. Execute /clavix:summarize if conversation exists\n' +
+            '  3. Use clavix plan --session <id> if saved session available\n\n' +
+            'Select option and execute, then retry this command.');
+    }
+    /**
+     * Error: No tasks.md found for specified project
+     * Used by: implement.ts
+     */
+    static noTasksFound(projectName) {
+        return (`No tasks.md found for project: ${projectName}\n\n` +
+            'Agent recovery options:\n' +
+            `  1. Execute: clavix plan --project ${projectName}\n` +
+            '  2. Or execute /clavix:plan to generate interactively\n\n' +
+            'After task generation completes, retry implementation.');
+    }
+    /**
+     * Error: .clavix-implement-config.json not found
+     * Used by: task-complete.ts, implement workflow
+     */
+    static configNotFound() {
+        return ('Configuration file not found: .clavix-implement-config.json\n\n' +
+            'Agent recovery:\n' +
+            '  1. Run: clavix implement\n' +
+            '  2. Wait for user to select git strategy\n' +
+            '  3. Config will be created automatically\n' +
+            '  4. Then retry task completion\n\n' +
+            'This is expected on first run.');
+    }
+    /**
+     * Error: Specified task ID not found in tasks.md
+     * Used by: task-complete.ts
+     */
+    static taskNotFound(taskId, availableTasks) {
+        const taskList = availableTasks
+            .map(t => {
+            const status = t.completed ? '[x]' : '[ ]';
+            return `  ${status} ${t.id} - ${t.description}`;
+        })
+            .join('\n');
+        return (`Task ID not found: ${taskId}\n\n` +
+            'Available task IDs:\n' +
+            taskList + '\n\n' +
+            'Select a valid task ID from the list above and retry.');
+    }
+    /**
+     * Error: Archive validation failed (prerequisites not met)
+     * Used by: archive.ts
+     */
+    static archiveValidationFailed(reason) {
+        return (`Archive validation failed: ${reason}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Check task completion status\n' +
+            '  2. Use --force flag if project is truly complete\n' +
+            '  3. Or complete remaining tasks first\n\n' +
+            'Ensure prerequisites are met before archiving.');
+    }
+    /**
+     * Error: File operation failed (write, read, move, delete)
+     * Used by: Multiple commands performing file operations
+     */
+    static fileOperationFailed(operation, path, error) {
+        const errorDetail = error ? `\nError: ${error}` : '';
+        return (`File operation failed: ${operation} at ${path}${errorDetail}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Verify path exists and is correct\n' +
+            '  2. Check file/directory permissions\n' +
+            '  3. Ensure no other process is accessing the file\n' +
+            '  4. Check available disk space\n\n' +
+            'Fix the underlying issue and retry.');
+    }
+    /**
+     * Error: Multiple PRD projects found, need user selection
+     * Used by: plan.ts, implement.ts when --project not specified
+     */
+    static multiplePrdsFound(projects) {
+        const projectList = projects.map((p, i) => `  ${i + 1}. ${p}`).join('\n');
+        return ('Multiple PRD projects found:\n\n' +
+            projectList + '\n\n' +
+            'Agent recovery options:\n' +
+            '  1. Specify project explicitly: --project <name>\n' +
+            '  2. Or run CLI in interactive mode to let user select\n\n' +
+            'Cannot proceed without project selection.');
+    }
+    /**
+     * Error: tasks.md already exists with progress
+     * Used by: plan.ts when generating tasks
+     */
+    static tasksExistWithProgress(completedCount, totalCount) {
+        return (`tasks.md already exists with progress: ${completedCount}/${totalCount} tasks completed\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Keep existing tasks.md and edit manually\n' +
+            '  2. Use --overwrite flag to regenerate (progress will be lost)\n' +
+            '  3. Cancel plan generation\n\n' +
+            'Ask user which option to proceed with.');
+    }
+    /**
+     * Error: Git repository not initialized
+     * Used by: implement.ts, task-complete.ts when git features expected
+     */
+    static gitNotInitialized() {
+        return ('Git repository not detected\n\n' +
+            'Auto-commit features are disabled.\n\n' +
+            'To enable git integration:\n' +
+            '  1. Run: git init\n' +
+            '  2. Or use --no-git flag to skip git features\n\n' +
+            'Proceeding without git auto-commit.');
+    }
+    /**
+     * Error: No archivable projects found
+     * Used by: archive.ts
+     */
+    static noArchivableProjects() {
+        return ('No archivable projects found\n\n' +
+            'Possible reasons:\n' +
+            '  • No PRD projects in .clavix/outputs/\n' +
+            '  • All projects already archived\n' +
+            '  • No projects with completed tasks\n\n' +
+            'Agent recovery options:\n' +
+            '  1. Run: clavix archive --list to see archived projects\n' +
+            '  2. Check: .clavix/outputs/ for active projects\n' +
+            '  3. Or create new PRD with /clavix:prd');
+    }
+    /**
+     * Error: Restoration failed due to name conflict
+     * Used by: archive.ts --restore
+     */
+    static restoreConflict(projectName) {
+        return (`Restoration conflict: Project "${projectName}" already exists in active outputs\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Archive the active project first\n' +
+            '  2. Manually rename one of the projects\n' +
+            '  3. Cancel restoration\n\n' +
+            'Ask user which option to proceed with.');
+    }
+    /**
+     * Error: CLI command execution failed
+     * Used by: When running CLI commands via Bash tool
+     */
+    static cliExecutionFailed(command, exitCode, stderr) {
+        const errorDetail = stderr ? `\n\nError output:\n${stderr}` : '';
+        return (`CLI command failed: ${command}\n` +
+            `Exit code: ${exitCode}${errorDetail}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Check command syntax is correct\n' +
+            '  2. Verify Clavix is installed: clavix --version\n' +
+            '  3. Check for error details above\n' +
+            '  4. Retry with corrected parameters\n\n' +
+            'Fix the issue and retry.');
+    }
+    /**
+     * Error: Invalid task ID format
+     * Used by: task-complete.ts
+     */
+    static invalidTaskIdFormat(taskId) {
+        return (`Invalid task ID format: ${taskId}\n\n` +
+            'Expected format: phase-{number}-{sanitized-phase-name}-{counter}\n\n' +
+            'Examples:\n' +
+            '  • phase-1-setup-1\n' +
+            '  • phase-2-user-authentication-3\n' +
+            '  • phase-3-api-integration-1\n\n' +
+            'Check tasks.md for correct task IDs and retry.');
+    }
+    /**
+     * Error: Session not found
+     * Used by: Commands using --session flag
+     */
+    static sessionNotFound(sessionId) {
+        return (`Session not found: ${sessionId}\n\n` +
+            'Agent recovery options:\n' +
+            '  1. Verify session ID is correct\n' +
+            '  2. List available sessions (if supported)\n' +
+            '  3. Use --active-session flag for current session\n' +
+            '  4. Or generate PRD without session\n\n' +
+            'Session may have expired or never existed.');
+    }
+    /**
+     * Warning: Task already completed
+     * Used by: task-complete.ts when marking already-done task
+     */
+    static taskAlreadyCompleted(taskId) {
+        return (`Task already completed: ${taskId}\n\n` +
+            'This task is marked as [x] in tasks.md.\n\n' +
+            'Agent options:\n' +
+            '  1. Proceed to next incomplete task\n' +
+            '  2. Use --force to mark again (updates tracking)\n' +
+            '  3. Check if this was intended\n\n' +
+            'No action needed unless forced.');
+    }
+}
+exports.AgentErrorMessages = AgentErrorMessages;
+//# sourceMappingURL=agent-error-messages.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clavix",
-  "version": "2.5.0",
-  "description": "Transform vague ideas into production-ready prompts. CLI tool using the CLEAR framework to analyze, improve, and generate PRDs for AI coding assistants (Claude Code, Cursor, Windsurf, and more)",
+  "version": "2.6.0",
+  "description": "Transform vague ideas into production-ready prompts. AI agent tool with CLI interface using the CLEAR framework to analyze, improve, and generate PRDs for AI coding assistants (Claude Code, Cursor, Windsurf, and more)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {