clavix 2.8.1 → 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

@@ -20,6 +20,7 @@ Use these instructions when your agent can only read documentation (no slash-com
 | `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

@@ -18,6 +18,7 @@ When working with this project, you can use the following Clavix commands:
 - `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

package/dist/templates/agents/octo.md

@@ -270,6 +270,7 @@ When starting implementation with `clavix implement`:
 | `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

@@ -17,6 +17,7 @@ Clavix helps Warp developers turn rough ideas into CLEAR, AI-ready prompts and P
 - `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/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.1",
+  "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",