clavix 2.8.0 → 2.8.2

package/README.md

@@ -46,6 +46,11 @@ clavix init
 /clavix:execute  # Interactive selection of saved prompts
 /clavix:prompts  # Manage prompt lifecycle
 
+# 4. Implement with task tracking (v2.8+)
+clavix plan              # Generate tasks from PRD
+clavix implement         # Start implementation workflow
+clavix task-complete <taskId>  # Mark tasks done with auto-commit
+
 # Or via CLI
 clavix execute --latest
 clavix prompts list
@@ -68,13 +73,31 @@ Clavix now automatically saves prompts from fast/deep optimization, allowing you
 3. **Execute**: `/clavix:execute` or `clavix execute --latest` → Implement when ready
 4. **Cleanup**: `clavix prompts clear --executed` → Remove completed prompts
 
+**Prompt Saving Modes (v2.8.1 clarification):**
+
+**CLI Usage (Auto-Save)**:
+```bash
+clavix fast "prompt"     # Automatically saves to .clavix/outputs/prompts/fast/
+clavix deep "prompt"     # Automatically saves to .clavix/outputs/prompts/deep/
+```
+CLI has direct file system access – saving is automatic.
+
+**Slash Command Usage (Agent Manual Save)**:
+```bash
+/clavix:fast "prompt"    # Agent must follow template saving instructions
+/clavix:deep "prompt"    # Agent must follow template saving instructions
+```
+Slash commands run through AI agent that must use tools per template.
+
+**Why the difference?** CLI runs directly in Node.js with file access, while slash commands require agent execution of Write tool.
+
 **Storage hygiene:**
 - Age warnings: >7 days = OLD, >30 days = STALE
 - Safety confirmations before deletion
 - Smart recommendations for cleanup
 - Keep <20 active prompts recommended
 
-Learn more: [Complete prompt lifecycle documentation](#prompt-management-commands)
+Learn more: [Complete prompt lifecycle documentation](docs/commands/execute.md)
 
 ### Direct CLI Usage (Alternative)
 

package/dist/templates/agents/agents.md

@@ -12,14 +12,15 @@ Use these instructions when your agent can only read documentation (no slash-com
 | Command | Purpose |
 | --- | --- |
 | `clavix init` | Interactive setup. Select providers and generate documentation/command files. |
-| `clavix fast "<prompt>"` | CLEAR (C/L/E) analysis with improved prompt output. Auto-saves to `.clavix/outputs/prompts/fast/`. |
-| `clavix deep "<prompt>"` | Full CLEAR (C/L/E/A/R) analysis, alternative variations, validation checklists. Auto-saves to `.clavix/outputs/prompts/deep/`. |
+| `clavix fast "<prompt>"` | CLEAR (C/L/E) analysis with improved prompt output. CLI auto-saves to `.clavix/outputs/prompts/fast/`. When using slash commands, agent must save manually per template instructions. |
+| `clavix deep "<prompt>"` | Full CLEAR (C/L/E/A/R) analysis, alternative variations, validation checklists. CLI auto-saves to `.clavix/outputs/prompts/deep/`. When using slash commands, agent must save manually per template instructions. |
 | `clavix execute [--latest]` | Execute saved prompts from fast/deep optimization. Interactive selection or `--latest` for most recent. |
 | `clavix prompts list` | View all saved prompts with status (NEW, EXECUTED, OLD, STALE) and storage statistics. |
 | `clavix prompts clear` | Manage prompt cleanup. Supports `--executed`, `--stale`, `--fast`, `--deep`, `--all` flags. |
 | `clavix prd` | Guided Socratic questions that generate `full-prd.md` and `quick-prd.md`. |
 | `clavix plan` | Transform PRDs or sessions into phase-based `tasks.md`. |
 | `clavix implement [--commit-strategy=<type>]` | Start task execution. Git strategies: per-task, per-5-tasks, per-phase, none (default: none). |
+| `clavix task-complete <taskId>` | Mark task as completed with validation and optional git commit. Auto-displays next task. |
 | `clavix start` | Begin conversational capture session for requirements gathering. |
 | `clavix summarize [session-id]` | Extract mini PRD and optimized prompts from saved sessions. |
 | `clavix list` | List sessions and/or output projects (`--sessions`, `--outputs`, filters). |

package/dist/templates/agents/copilot-instructions.md

@@ -11,13 +11,14 @@ Clavix is a CLEAR Framework-validated prompt engineering toolkit that helps impr
 When working with this project, you can use the following Clavix commands:
 
 ### Prompt Improvement
-- `clavix fast "<prompt>"` - Quick CLEAR analysis (C/L/E components) with improved prompt output
-- `clavix deep "<prompt>"` - Comprehensive CLEAR analysis (all 5 components: C/L/E/A/R) with alternatives and validation
+- `clavix fast "<prompt>"` - Quick CLEAR analysis (C/L/E components) with improved prompt output. CLI auto-saves; slash commands require manual saving per template instructions.
+- `clavix deep "<prompt>"` - Comprehensive CLEAR analysis (all 5 components: C/L/E/A/R) with alternatives and validation. CLI auto-saves; slash commands require manual saving per template instructions.
 
 ### Strategic Planning
 - `clavix prd` - Interactive PRD generation through Socratic questioning
 - `clavix plan` - Transform PRDs into phase-based implementation tasks
 - `clavix implement [--commit-strategy=<type>]` - Execute tasks with progress tracking (git: per-task, per-5-tasks, per-phase, none [default])
+- `clavix task-complete <taskId>` - Mark task as completed with validation and optional git commit
 
 ### Conversational Workflows
 - `clavix start` - Begin conversational session for requirements gathering
@@ -52,7 +53,7 @@ Clavix now automatically saves optimized prompts from fast/deep commands for lat
   - `--force` - Skip confirmation prompts
 
 **Prompt Lifecycle Workflow:**
-1. Optimize: `clavix fast/deep "<prompt>"` → Auto-saved to `.clavix/outputs/prompts/`
+1. Optimize: `clavix fast/deep "<prompt>"` → CLI auto-saves; slash commands require manual saving
 2. Review: `clavix prompts list` → View all saved prompts with status
 3. Execute: `clavix execute --latest` → Implement when ready
 4. Cleanup: `clavix prompts clear --executed` → Remove completed prompts

package/dist/templates/agents/octo.md

@@ -263,13 +263,14 @@ When starting implementation with `clavix implement`:
 | Command | Use it for |
 | --- | --- |
 | `clavix init` | Rebuild `.clavix` structure and regenerate provider assets. |
-| `clavix fast` / `clavix deep` | CLEAR-based prompt improvement (quick vs. comprehensive). Auto-saves prompts to `.clavix/outputs/prompts/`. |
+| `clavix fast` / `clavix deep` | CLEAR-based prompt improvement (quick vs. comprehensive). CLI auto-saves prompts. Slash commands require manual saving per template instructions. |
 | `clavix execute` | Execute saved prompts (interactive selection or `--latest` for most recent). |
 | `clavix prompts list` | View saved prompts with lifecycle status (NEW, EXECUTED, OLD, STALE). |
 | `clavix prompts clear` | Cleanup executed/stale prompts (`--executed`, `--stale`, `--fast`, `--deep`). |
 | `clavix prd` | Guided questions to create PRDs. |
 | `clavix plan` | Convert PRD artifacts into task lists. |
 | `clavix implement [--commit-strategy=<type>]` | Start task execution (git: per-task, per-5-tasks, per-phase, none [default]). |
+| `clavix task-complete <taskId>` | Mark task completed with validation and optional git commit. Auto-displays next task. |
 | `clavix start` | Capture conversational requirements. |
 | `clavix summarize` | Extract mini PRDs and prompts from sessions. |
 | `clavix list` | List sessions or outputs (use `--sessions`, `--outputs`, `--archived`). |

package/dist/templates/agents/warp.md

@@ -9,14 +9,15 @@ Clavix helps Warp developers turn rough ideas into CLEAR, AI-ready prompts and P
 
 ### Common commands
 - `clavix init` – interactive provider setup (regenerates docs & commands)
-- `clavix fast "<prompt>"` – quick CLEAR (C/L/E) analysis and improved prompt. Auto-saves to `.clavix/outputs/prompts/fast/`.
-- `clavix deep "<prompt>"` – full CLEAR (C/L/E/A/R) analysis with alternatives & checklists. Auto-saves to `.clavix/outputs/prompts/deep/`.
+- `clavix fast "<prompt>"` – quick CLEAR (C/L/E) analysis and improved prompt. CLI auto-saves; slash commands need manual saving per template instructions.
+- `clavix deep "<prompt>"` – full CLEAR (C/L/E/A/R) analysis with alternatives & checklists. CLI auto-saves; slash commands need manual saving per template instructions.
 - `clavix execute [--latest]` – execute saved prompts from fast/deep. Interactive selection or `--latest` for most recent.
 - `clavix prompts list` – view all saved prompts with age/status (NEW, EXECUTED, OLD, STALE)
 - `clavix prompts clear [--executed|--stale|--fast|--deep]` – cleanup executed or old prompts
 - `clavix prd` – answer focused questions to create full/quick PRDs
 - `clavix plan` – transform PRDs or sessions into task lists
 - `clavix implement [--commit-strategy=<type>]` – execute tasks (git: per-task, per-5-tasks, per-phase, none [default])
+- `clavix task-complete <taskId>` – mark task completed with validation and optional git commit
 - `clavix start` – capture requirement conversations in Warp
 - `clavix summarize [session-id]` – extract mini PRDs and optimized prompts
 - `clavix list` – list sessions/outputs (`--sessions`, `--outputs`, `--archived`)

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

@@ -155,11 +155,110 @@ Output:
 
 ## Next Steps (v2.7+)
 
-After deep analysis completes, the prompt is automatically saved to `.clavix/outputs/prompts/deep/`.
+### Saving the Prompt (REQUIRED)
+
+After displaying the CLEAR-optimized prompt, you MUST save it to ensure it's available for the prompt lifecycle workflow.
+
+**If user ran CLI command** (`clavix deep "prompt"`):
+- Prompt is automatically saved ✓
+- Skip to "Executing the Saved Prompt" section below
+
+**If you are executing this slash command** (`/clavix:deep`):
+- You MUST save the prompt manually
+- Follow these steps:
+
+#### Step 1: Create Directory Structure
+```bash
+mkdir -p .clavix/outputs/prompts/deep
+```
+
+#### Step 2: Generate Unique Prompt ID
+Create a unique identifier using this format:
+- **Format**: `deep-YYYYMMDD-HHMMSS-<random>`
+- **Example**: `deep-20250117-143022-a3f2`
+- Use current timestamp + random 4-character suffix
+
+#### Step 3: Save Prompt File
+Use the Write tool to create the prompt file at:
+- **Path**: `.clavix/outputs/prompts/deep/<prompt-id>.md`
+
+**File content format**:
+```markdown
+---
+id: <prompt-id>
+source: deep
+timestamp: <ISO-8601 timestamp>
+executed: false
+originalPrompt: <user's original prompt text>
+---
+
+# Improved Prompt
+
+<Insert the CLEAR-optimized prompt content from your analysis above>
+
+## CLEAR Scores
+- **C** (Conciseness): <percentage>%
+- **L** (Logic): <percentage>%
+- **E** (Explicitness): <percentage>%
+- **A** (Adaptiveness): <percentage>%
+- **R** (Reflectiveness): <percentage>%
+- **Overall**: <percentage>% (<rating>)
+
+## Alternative Variations
+
+<Insert adaptive variations from your analysis>
+
+## Reflection Checklist
+
+<Insert reflective validation from your analysis>
+
+## Original Prompt
+```
+<user's original prompt text>
+```
+```
+
+#### Step 4: Update Index File
+Use the Write tool to update the index at `.clavix/outputs/prompts/deep/.index.json`:
+
+**If index file doesn't exist**, create it with:
+```json
+{
+  "version": "1.0",
+  "prompts": []
+}
+```
+
+**Then add a new metadata entry** to the `prompts` array:
+```json
+{
+  "id": "<prompt-id>",
+  "filename": "<prompt-id>.md",
+  "source": "deep",
+  "timestamp": "<ISO-8601 timestamp>",
+  "createdAt": "<ISO-8601 timestamp>",
+  "path": ".clavix/outputs/prompts/deep/<prompt-id>.md",
+  "originalPrompt": "<user's original prompt text>",
+  "executed": false,
+  "executedAt": null
+}
+```
+
+**Important**: Read the existing index first, append the new entry to the `prompts` array, then write the updated index back.
+
+#### Step 5: Verify Saving Succeeded
+Confirm:
+- File exists at `.clavix/outputs/prompts/deep/<prompt-id>.md`
+- Index file updated with new entry
+- Display success message: `✓ Prompt saved: <prompt-id>.md`
+
+### Executing the Saved Prompt
+
+After saving completes successfully:
 
 **Execute immediately:**
 ```bash
-/clavix:execute
+/clavix:execute --latest
 ```
 
 **Review saved prompts first:**
@@ -201,6 +300,27 @@ clavix prompts clear --deep
 
 ## Troubleshooting
 
+### Issue: Prompt Not Saved
+
+**Error: Cannot create directory**
+```bash
+mkdir -p .clavix/outputs/prompts/deep
+```
+
+**Error: Index file corrupted or invalid JSON**
+```bash
+echo '{"version":"1.0","prompts":[]}' > .clavix/outputs/prompts/deep/.index.json
+```
+
+**Error: Duplicate prompt ID**
+- Generate a new ID with a different timestamp or random suffix
+- Retry the save operation with the new ID
+
+**Error: File write permission denied**
+- Check directory permissions
+- Ensure `.clavix/` directory is writable
+- Try creating the directory structure again
+
 ### Issue: Strategic scope detected but user wants to continue with deep mode
 **Cause**: User prefers deep analysis over PRD generation
 **Solution**:

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

@@ -138,11 +138,100 @@ Success Criteria:
 
 ## Next Steps (v2.7+)
 
-After fast optimization completes, the prompt is automatically saved to `.clavix/outputs/prompts/fast/`.
+### Saving the Prompt (REQUIRED)
+
+After displaying the CLEAR-optimized prompt, you MUST save it to ensure it's available for the prompt lifecycle workflow.
+
+**If user ran CLI command** (`clavix fast "prompt"`):
+- Prompt is automatically saved ✓
+- Skip to "Executing the Saved Prompt" section below
+
+**If you are executing this slash command** (`/clavix:fast`):
+- You MUST save the prompt manually
+- Follow these steps:
+
+#### Step 1: Create Directory Structure
+```bash
+mkdir -p .clavix/outputs/prompts/fast
+```
+
+#### Step 2: Generate Unique Prompt ID
+Create a unique identifier using this format:
+- **Format**: `fast-YYYYMMDD-HHMMSS-<random>`
+- **Example**: `fast-20250117-143022-a3f2`
+- Use current timestamp + random 4-character suffix
+
+#### Step 3: Save Prompt File
+Use the Write tool to create the prompt file at:
+- **Path**: `.clavix/outputs/prompts/fast/<prompt-id>.md`
+
+**File content format**:
+```markdown
+---
+id: <prompt-id>
+source: fast
+timestamp: <ISO-8601 timestamp>
+executed: false
+originalPrompt: <user's original prompt text>
+---
+
+# Improved Prompt
+
+<Insert the CLEAR-optimized prompt content from your analysis above>
+
+## CLEAR Scores
+- **C** (Conciseness): <percentage>%
+- **L** (Logic): <percentage>%
+- **E** (Explicitness): <percentage>%
+- **Overall**: <percentage>% (<rating>)
+
+## Original Prompt
+```
+<user's original prompt text>
+```
+```
+
+#### Step 4: Update Index File
+Use the Write tool to update the index at `.clavix/outputs/prompts/fast/.index.json`:
+
+**If index file doesn't exist**, create it with:
+```json
+{
+  "version": "1.0",
+  "prompts": []
+}
+```
+
+**Then add a new metadata entry** to the `prompts` array:
+```json
+{
+  "id": "<prompt-id>",
+  "filename": "<prompt-id>.md",
+  "source": "fast",
+  "timestamp": "<ISO-8601 timestamp>",
+  "createdAt": "<ISO-8601 timestamp>",
+  "path": ".clavix/outputs/prompts/fast/<prompt-id>.md",
+  "originalPrompt": "<user's original prompt text>",
+  "executed": false,
+  "executedAt": null
+}
+```
+
+**Important**: Read the existing index first, append the new entry to the `prompts` array, then write the updated index back.
+
+#### Step 5: Verify Saving Succeeded
+Confirm:
+- File exists at `.clavix/outputs/prompts/fast/<prompt-id>.md`
+- Index file updated with new entry
+- Display success message: `✓ Prompt saved: <prompt-id>.md`
+
+### Executing the Saved Prompt
+
+After saving completes successfully:
 
 **Execute immediately:**
 ```bash
-/clavix:execute
+/clavix:execute --latest
 ```
 
 **Review saved prompts first:**
@@ -183,6 +272,27 @@ clavix prompts clear --fast
 
 ## Troubleshooting
 
+### Issue: Prompt Not Saved
+
+**Error: Cannot create directory**
+```bash
+mkdir -p .clavix/outputs/prompts/fast
+```
+
+**Error: Index file corrupted or invalid JSON**
+```bash
+echo '{"version":"1.0","prompts":[]}' > .clavix/outputs/prompts/fast/.index.json
+```
+
+**Error: Duplicate prompt ID**
+- Generate a new ID with a different timestamp or random suffix
+- Retry the save operation with the new ID
+
+**Error: File write permission denied**
+- Check directory permissions
+- Ensure `.clavix/` directory is writable
+- Try creating the directory structure again
+
 ### Issue: Triage keeps recommending deep mode
 **Cause**: Prompt has low CLEAR scores + multiple secondary indicators
 **Solution**:

package/dist/templates/slash-commands/_canonical/task-complete.md

@@ -0,0 +1,188 @@
+---
+name: "Clavix: Task Complete"
+description: Mark a task as completed with validation and optional git commit
+---
+
+# Clavix Task Complete - Mark Implementation Task Done
+
+You are helping the user mark a task as completed during implementation workflow.
+
+## Instructions
+
+1. **Prerequisites**:
+   - User must have run `clavix implement` to start implementation
+   - `.clavix-implement-config.json` must exist in PRD folder
+   - `tasks.md` must be generated from `clavix plan`
+
+2. **Verify the task ID**:
+
+   a. **Read tasks.md** to find the task ID:
+      - Task IDs are in format: `**phase-1-feature-1**`
+      - Located before each task description
+      - Example: `- [ ] **phase-1-auth-1** - Implement user authentication`
+
+   b. **Confirm with user** if task ID is unclear:
+      ```
+      I see these incomplete tasks:
+      - phase-1-auth-1: Implement user authentication
+      - phase-1-auth-2: Add password reset flow
+
+      Which task did you complete? (or provide task ID)
+      ```
+
+3. **Mark task as completed**:
+
+   **Run the CLI command**:
+   ```bash
+   clavix task-complete <task-id>
+   ```
+
+   **Examples**:
+   ```bash
+   clavix task-complete phase-1-auth-1
+   clavix task-complete phase-2-api-3
+   clavix task-complete setup-1
+   ```
+
+4. **The command will automatically**:
+   - Validate task exists in tasks.md
+   - Mark checkbox as `[x]` in tasks.md
+   - Update config file with completion tracking
+   - Show progress statistics (X/Y tasks completed)
+   - Create git commit (if strategy enabled and conditions met)
+   - Display next incomplete task
+
+5. **Git auto-commit behavior**:
+
+   The command respects the git strategy configured in `clavix implement`:
+
+   - **`none`** (default): No automatic commits
+   - **`per-task`**: Creates commit after this completion
+   - **`per-5-tasks`**: Creates commit if 5 tasks completed (modulo 5 == 0)
+   - **`per-phase`**: Creates commit if all tasks in current phase are done
+
+   **Override for specific task**:
+   ```bash
+   clavix task-complete phase-1-auth-1 --no-git
+   ```
+   Skips git commit even if strategy is enabled (useful for experimental changes).
+
+6. **Handle command output**:
+
+   a. **Success case**:
+   ```
+   ✓ Task marked as completed
+   ✓ Configuration updated
+
+   Progress:
+     Completed: 5/20 tasks (25%)
+     Remaining: 15 tasks
+
+   Next Task:
+     ID: phase-1-auth-2
+     Add password reset flow
+     Reference: Full PRD section "Authentication > Password Reset"
+   ```
+
+   b. **Already completed case**:
+   ```
+   ⚠ Task "phase-1-auth-1" is already marked as completed
+
+   Use --force to re-mark this task as completed.
+
+   Next Task:
+     ID: phase-1-auth-2
+     ...
+   ```
+
+   c. **All tasks complete**:
+   ```
+   ✓ Task marked as completed
+   🎉 All tasks completed!
+
+   Great work! All implementation tasks are done.
+
+   Hint: Run "clavix archive" to archive this project
+   ```
+
+7. **After task completion**:
+
+   a. **If more tasks remaining**:
+      - Acknowledge the completion
+      - Ask user: "Ready to start the next task? [display next task description]"
+      - Or: "Would you like to implement the next task now?"
+
+   b. **If all tasks complete**:
+      - Congratulate the user
+      - Suggest running `clavix archive` to archive the project
+      - Ask if they want to create a final git commit or tag
+
+8. **Error recovery**:
+
+   **If task ID not found**:
+   ```
+   ✗ Task ID "phase-1-invalid" not found
+
+   Available task IDs:
+     Phase 1: Authentication
+       [ ] phase-1-auth-1 - Implement user authentication
+       [ ] phase-1-auth-2 - Add password reset flow
+   ```
+
+   - The command lists all available tasks
+   - Ask user to verify task ID
+   - Or ask which task they meant to complete
+
+   **If config file not found**:
+   ```
+   No config files found.
+
+   Hint: Run "clavix implement" first to initialize
+   ```
+
+   - Tell user to run `clavix implement` first
+   - This starts the implementation workflow
+
+   **If file write error**:
+   ```
+   ✗ Failed to mark task as completed
+
+   Recovery Options:
+     1. Check if tasks.md file is readable and writable
+     2. Verify task ID matches exactly
+     3. Try running with --force flag
+     4. Check tasks.md.backup file if created
+   ```
+
+   - Follow recovery suggestions
+   - Check file permissions
+   - Ask user if they manually edited tasks.md
+
+## Command Flags
+
+- `--no-git`: Skip git commit even if strategy is enabled
+- `-f, --force`: Force completion even if already marked complete
+- `-c, --config <path>`: Specify custom config file path (defaults to auto-discover)
+
+## Best Practices
+
+1. **Never manually edit tasks.md checkboxes** - Always use `clavix task-complete`
+2. **Verify task completion** - Ensure implementation is done before marking
+3. **Use --no-git for experiments** - Skip commits for work-in-progress changes
+4. **Check next task** - Command automatically shows what to work on next
+5. **Track progress** - Use progress stats to estimate remaining work
+
+## Related Commands
+
+- `clavix implement` - Start implementation workflow (shows current task)
+- `clavix plan` - Generate tasks.md from PRD
+- `clavix archive` - Archive completed project (run after all tasks done)
+
+## Next Steps
+
+After completing all tasks:
+1. Run `clavix archive` to archive the implementation
+2. Create final git commit or tag
+3. Update CHANGELOG if needed
+4. Merge feature branch
+5. Deploy or release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "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)",
   "type": "module",
   "main": "dist/index.js",