clavix 2.4.3 → 2.5.1

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**:
 
@@ -47,56 +48,64 @@ You are helping the user implement tasks from their task plan with AI assistance
       - Use PRD requirements as your guide
       - Ask user for clarification if needed
 
-   e. **Mark task as completed**:
-      - In `tasks.md`, change `- [ ] Task description` to `- [x] Task description`
-      - Update only the specific task you just completed
-
-   f. **Create git commit (if enabled)**:
-      - Check the `commitStrategy` in config
-      - If `per-task`: commit after each task
-      - If `per-5-tasks`: commit after every 5 tasks
-      - If `per-phase`: commit when all tasks in a phase are done
-      - Use descriptive commit messages with task description
-
-   g. **Move to next task**:
-      - Find the next `- [ ]` task in tasks.md
-      - Repeat the process
+   e. **Complete the task programmatically**:
+      - IMPORTANT: NEVER manually edit checkboxes in tasks.md
+      - Instead, run: `clavix task-complete {task-id}`
+      - The task ID is found in tasks.md (e.g., `phase-1-authentication-1`)
+      - This command automatically:
+        • Validates the task exists
+        • Updates the checkbox in tasks.md
+        • Tracks completion in config file
+        • Creates git commit (if strategy enabled)
+        • Displays the next task
+      - Example: `clavix task-complete phase-1-setup-1`
+
+   f. **Move to next task**:
+      - The task-complete command shows the next task automatically
+      - Read it and repeat the process
+      - If you get interrupted, just run `clavix implement` again to resume
 
 3. **Session Resume**:
    - When user runs `clavix implement` again, it automatically picks up from the last incomplete task
    - No manual tracking needed - the checkboxes in tasks.md are the source of truth
 
-## Git Commit Format
+## Task Completion Workflow
+
+**CRITICAL: Always use the `clavix task-complete` command**
 
-When creating commits, use this format:
+```bash
+# After implementing a task
+clavix task-complete {task-id}
 
+# Example
+clavix task-complete phase-1-setup-1
 ```
-clavix: [task description]
 
-Completed tasks:
-- Task 1
-- Task 2
+The command handles:
+- Checkbox updates in tasks.md
+- Config file tracking
+- Git commits (per strategy)
+- Progress display
+- Next task retrieval
 
-Project: [project-name]
-Generated by Clavix /clavix:implement
-```
+**NEVER manually edit tasks.md checkboxes** - the command ensures proper tracking and prevents state inconsistencies.
 
 ## Important Rules
 
 **DO**:
-- Read tasks.md to find the current task
+- Read tasks.md to find the current task and its ID
 - Implement ONE task at a time
-- Mark tasks complete by changing `[ ]` to `[x]`
-- Create commits based on the strategy in config
+- Use `clavix task-complete {task-id}` after completing each task
 - Reference the PRD for detailed requirements
 - Ask for clarification when tasks are ambiguous
+- Run `clavix implement` again if interrupted to resume
 
 **DON'T**:
+- NEVER manually edit checkboxes in tasks.md
 - Skip tasks or implement out of order
 - Mark tasks complete before actually implementing them
-- Modify multiple tasks' checkboxes at once (only current task)
-- Create commits if strategy is 'none'
 - Assume what code to write - use PRD as source of truth
+- Try to track task completion manually
 
 ## Task Blocking Protocol
 
@@ -177,17 +186,40 @@ Which option would you like?"
 
 ```
 1. User runs: clavix implement
-2. Command shows: "Next task: Implement user authentication"
+2. Command shows: "Next task (ID: phase-1-auth-1): Implement user authentication"
 3. You (AI agent):
    - Read PRD authentication requirements
    - Implement auth logic
    - Write tests
-   - Update tasks.md: - [x] Implement user authentication
-   - Create git commit (if enabled)
-   - Find next task in tasks.md
-   - Continue or wait for user
+   - Run: clavix task-complete phase-1-auth-1
+   - Command automatically:
+     • Marks task complete in tasks.md
+     • Updates config tracking
+     • Creates git commit (if enabled)
+     • Shows next task
+   - Continue with next task or wait for user
 ```
 
+## Finding Task IDs
+
+Task IDs are visible in several places:
+1. When you read `tasks.md` - they're in the format `phase-X-name-Y`
+2. In the config file (`.clavix-implement-config.json`) under `currentTask.id`
+3. When running `clavix implement` - shown next to task description
+
+Example tasks.md structure:
+```markdown
+## Phase 1: Authentication
+
+- [ ] Implement user registration (ref: User Management)
+  Task ID: phase-1-authentication-1
+
+- [ ] Add JWT token generation (ref: User Management)
+  Task ID: phase-1-authentication-2
+```
+
+To find the task ID programmatically, read tasks.md and look for the pattern `phase-{number}-{sanitized-phase-name}-{counter}`.
+
 ## Workflow Navigation
 
 **You are here:** Implement (Task Execution)
@@ -219,6 +251,28 @@ Which option would you like?"
 - CLI creates config and shows first task
 - AI agent should wait for config before proceeding
 
+### Issue: `clavix task-complete` command not found
+**Cause**: Clavix version doesn't have task-complete command OR not in PATH
+**Solution**:
+- Check Clavix version: `clavix --version`
+- Ensure Clavix is up to date: `npm install -g clavix@latest`
+- If issue persists, report bug to Clavix maintainers
+
+### Issue: Task ID not found by task-complete
+**Cause**: Task ID doesn't match what's in tasks.md
+**Solution**:
+- Read tasks.md to see actual task IDs
+- Task IDs follow pattern: `{sanitized-phase-name}-{counter}`
+- Run `clavix task-complete` without arguments to see available tasks
+- Example: `phase-1-authentication-1` not `Phase 1 Authentication 1`
+
+### Issue: Task already marked complete
+**Cause**: Task was completed in previous session or manually
+**Solution**:
+- Use `--force` flag: `clavix task-complete {task-id} --force`
+- Or skip to next task shown by `clavix implement`
+- Config will be updated to track the completion
+
 ### Issue: Cannot find next incomplete task in tasks.md
 **Cause**: All tasks completed OR tasks.md corrupted
 **Solution**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "2.4.3",
+  "version": "2.5.1",
   "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)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",