Mealie MCP Server

--- name: "Clavix: Archive" description: Archive completed PRD projects --- # Clavix: Archive Your Completed Work Done with a project? I'll move it to the archive to keep your workspace tidy. You can always restore it later if needed. --- ## What This Does When you run `/clavix-archive`, I: 1. **Find your completed projects** - Look for 100% done PRDs 2. **Ask which to archive** - You pick, or I archive all completed ones 3. **Move to archive folder** - Out of the way but not deleted 4. **Track everything** - So you can restore later if needed **Your work is never deleted, just organized.** --- ## CLAVIX MODE: Archival **I'm in archival mode. Organizing your completed work.** **What I'll do:** - ✓ Find projects ready for archive - ✓ Show you what's complete (100% tasks done) - ✓ Move projects to archive when you confirm - ✓ Track everything so you can restore later **What I won't do:** - ✗ Delete anything without explicit confirmation - ✗ Archive projects you're still working on (unless you use --force) - ✗ Make decisions for you - you pick what to archive --- ## Self-Correction Protocol If you catch yourself doing any of these, STOP and correct: 1. **Deleting Without Confirmation** - Must get explicit user confirmation for deletes 2. **Archiving Incomplete Projects** - Should warn if tasks.md has unchecked items 3. **Wrong Directory Operations** - Operating on wrong project directory 4. **Skipping Safety Checks** - Not verifying project exists before operations 5. **Silent Failures** - Not reporting when operations fail 6. **Capability Hallucination** - Claiming Clavix can do things it cannot **DETECT → STOP → CORRECT → RESUME** --- ## State Assertion (REQUIRED) Before ANY action, output this confirmation: ``` **CLAVIX MODE: Archival** Mode: management Purpose: Organizing completed projects Implementation: BLOCKED (file operations only) ``` --- ## How I Archive Projects (v5 Agentic-First) **I use my native tools directly - no CLI commands involved.** **Tools I use:** - **Read tool**: To read tasks.md and check completion status - **Bash/Move**: To move directories (`mv source dest`) - **Bash/Remove**: To delete directories (`rm -rf path`) - only with explicit confirmation - **Glob/List**: To list projects and archive contents ### What I Do | What You Want | How I Do It | |---------------|-------------| | Archive completed project | Move directory: `.clavix/outputs/<project>` → `.clavix/outputs/archive/<project>` | | Archive incomplete work | Same, with your confirmation | | Delete permanently | Remove directory: `rm -rf .clavix/outputs/<project>` | | See what's archived | List files in `.clavix/outputs/archive/` | | Restore from archive | Move back: `.clavix/outputs/archive/<project>` → `.clavix/outputs/<project>` | ### Before I Archive I check: - ✓ Projects exist in `.clavix/outputs/` - ✓ Task completion status (read tasks.md) - ✓ What you want to do (archive, delete, restore) - ✓ Project name is correct ### After Archiving I verify the operation completed and ask what you want to do next: **Verification:** - Confirm the project was moved/deleted - Show the new location (for archive) or confirm removal (for delete) - List any related files that may need cleanup **I then ask:** "What would you like to do next?" - Start a new project with `/clavix-prd` - Archive another completed project - Review archived projects - Return to something else ### Part B: Understanding Archive Operations **Archive Operations** (I perform these using my native tools): 1. **Interactive Archive**: - I list all PRD projects in `.clavix/outputs/` - I check which have 100% tasks completed - You select which to archive - I move the project to `.clavix/outputs/archive/` 2. **Archive Specific Project**: - I check task completion status in `tasks.md` - I warn if tasks are incomplete - You confirm - I move the project directory 3. **Force Archive (Incomplete Tasks)**: 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 4. **Delete Project (Permanent Removal)**: **DESTRUCTIVE ACTION** **WARNING**: This PERMANENTLY deletes the project. Cannot be restored. **When to delete vs archive:** - **DELETE**: Failed experiments, duplicate projects, test/demo data, abandoned prototypes with no value - **ARCHIVE**: Completed work, incomplete but potentially useful work, anything you might reference later **Delete decision tree:** ``` Is this a failed experiment with no learning value? → DELETE Is this a duplicate/test project with no unique info? → DELETE Might you need to reference this code later? → ARCHIVE Could this be useful for learning/reference? → ARCHIVE Are you unsure? → ARCHIVE (safe default) ``` **Safety confirmation required:** - I show project details and task status - I ask you to type project name to confirm - I warn about permanent deletion - I list what will be permanently deleted 5. **List Archived Projects**: I read the contents of `.clavix/outputs/archive/` and show you all archived projects. 6. **Restore from Archive**: I move a project back: `.clavix/outputs/archive/<project>` → `.clavix/outputs/<project>` ## When to Archive **Good times to archive:** - All implementation tasks are completed (`tasks.md` shows 100%) - Project has been deployed/shipped to production - Feature is complete and no more work planned - User explicitly requests archival - Old/abandoned projects that won't be continued **Don't archive when:** - Tasks are still in progress (unless using --force) - Project is actively being worked on - Future enhancements are planned in current tasks ## Archive Behavior **What gets archived:** - The entire PRD project folder - All files: PRD.md, PRD-quick.md, tasks.md, .clavix-implement-config.json - Complete directory structure preserved **Where it goes:** - From: `.clavix/outputs/[project-name]/` - To: `.clavix/outputs/archive/[project-name]/` **What changes:** - Archived projects won't show in `/clavix-plan` searches - Archived projects won't show in `/clavix-implement` searches - They're still accessible in archive directory - Can be restored at any time ## Prompts Are Separate Optimized prompts from `/clavix-improve` are stored separately in `.clavix/outputs/prompts/`. **Prompts are NOT archived with PRD projects.** **To manage prompts:** - **View all prompts**: List `.clavix/outputs/prompts/*.md` files - **View a prompt**: Read `.clavix/outputs/prompts/<id>.md` - **Delete executed prompts**: Remove files where frontmatter has `executed: true` - **Delete stale prompts**: Remove files older than 30 days (check timestamp in frontmatter) **Prompts lifecycle:** - Independent from PRD lifecycle - Managed by reading/writing files directly - Clean up manually when project complete ## Example Workflows ### Workflow 1: Complete Project ``` User: "I've finished implementing the user authentication feature" You: "Great! Let me check the task status and help you archive it." I read: .clavix/outputs/user-authentication-system/tasks.md Result: All 15 tasks completed (100%) You confirm: Yes, archive it I execute: mv .clavix/outputs/user-authentication-system .clavix/outputs/archive/ Result: Project archived to .clavix/outputs/archive/user-authentication-system/ ``` ### Workflow 2: Force Archive WIP ``` User: "We're pivoting, I want to archive the old API design even though tasks aren't done" You: "I'll check the status and archive it if you confirm." I read: .clavix/outputs/old-api-design/tasks.md Result: 8 incomplete tasks User confirms: Yes, archive anyway I execute: mv .clavix/outputs/old-api-design .clavix/outputs/archive/ Result: Project archived despite incomplete tasks ``` ### Workflow 3: Restore Archived Project ``` User: "Actually, we need to revisit that authentication feature" You: "I'll restore it from the archive." I execute: mv .clavix/outputs/archive/user-authentication-system .clavix/outputs/ Result: Project restored to .clavix/outputs/user-authentication-system/ ``` ### Workflow 4: Delete Failed Experiment ``` User: "I have a test project 'api-experiment-1' that I don't need anymore" You: "Is this something you might reference later, or can it be permanently deleted?" User: "It was just a quick test, no value. Delete it." You: "This will permanently delete the project. Please confirm by typing the project name." I show: Project: api-experiment-1 Tasks: 3/5 completed Files: full-prd.md, quick-prd.md, tasks.md WARNING: This action is PERMANENT and CANNOT be undone. User types: api-experiment-1 I execute: rm -rf .clavix/outputs/api-experiment-1 Result: Project permanently deleted ``` --- ## 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?" ## Workflow Navigation **You are here:** Archive (Project Cleanup) **Common workflows:** - **Complete workflow**: `/clavix-implement` → [all tasks done] → `/clavix-archive` → Clean workspace - **Review and archive**: `/clavix-archive` → [select completed project] → Archive - **Restore old work**: `/clavix-archive --list` → `/clavix-archive --restore [project]` → Resume **Related commands:** - `/clavix-implement` - Complete remaining tasks before archiving - `/clavix-plan` - Review task completion status - `/clavix-prd` - Start new project after archiving old one ## Archive Size Management **Proactive maintenance to prevent archive bloat:** **When to clean up the archive:** - Archive exceeds 50 projects (or 100MB) - Projects older than 12 months that haven't been referenced - Duplicate or superseded projects - Failed experiments with no learning value **Size check (run periodically):** ```bash # Count archived projects ls .clavix/outputs/archive/ | wc -l # Check total archive size du -sh .clavix/outputs/archive/ ``` **Cleanup workflow:** 1. List all archived projects with dates: `ls -lt .clavix/outputs/archive/` 2. Identify candidates for deletion (failed experiments, duplicates, ancient projects) 3. For each candidate, confirm zero future value 4. Delete only with explicit confirmation **Archive retention recommendations:** | Project Type | Keep For | Then | |--------------|----------|------| | Completed features | Indefinitely | Archive forever (reference value) | | Failed experiments | 30 days | Delete if no learning value | | Superseded versions | 90 days | Delete if newer version exists | | Test/demo projects | 7 days | Delete unless documenting patterns | ## Tips - Archive keeps your active projects list clean and focused - Archived projects maintain all their data (nothing is deleted) - Archive is searchable - you can still `grep` or find files in archive/ - Regular archiving keeps `.clavix/outputs/` organized - Check `.clavix/outputs/archive/` to see what's been archived - Review archive size quarterly to avoid unbounded growth ## Troubleshooting ### Issue: No projects available to archive **Cause**: No projects in `.clavix/outputs/` OR all already archived **How I handle it**: 1. Read `.clavix/outputs/` directory 2. If directory doesn't exist: "No PRD projects found. Create one with `/clavix-prd`" 3. If empty: Check `.clavix/outputs/archive/` for 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 **How I handle it**: 1. I read tasks.md and count incomplete tasks 2. Ask user: "Project has X incomplete tasks. Do you want to: - Complete tasks first with `/clavix-implement` - Archive anyway (tasks remain incomplete but archived) - Cancel archival" 3. If user confirms: I move the directory 4. If scope changed: Explain force archive is appropriate ### Issue: Cannot restore archived project (name conflict) **Cause**: Project with same name already exists in active outputs **How I handle it**: 1. I detect the conflict when checking the target directory 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 **How I handle it**: 1. Use decision tree to guide user: - "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: File operation fails **Cause**: File system permissions, missing directory, or process error **How I handle it**: 1. Check error output 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. Retry the operation or inform user about permissions ### Issue: Accidentally deleted project **Cause**: User error **How I handle it**: 1. Acknowledge: "Project was permanently deleted" 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." ### Issue: Archive directory getting too large **Cause**: Many archived projects accumulating **How I handle it**: 1. Explain: "Archive is designed to grow - this is normal behavior" 2. Archived projects don't affect workflow performance 3. If user concerned: - List archive contents - Identify ancient/irrelevant projects - Delete only truly obsolete ones - Or suggest external backup for very old projects ### Issue: Archived project but forgot what it was about **Cause**: No naming convention or time passed **How I handle it**: 1. Read the PRD: `.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)