@e0ipso/ai-task-manager 1.2.1 → 1.4.0

package/templates/assistant/commands/tasks/execute-task.md

@@ -0,0 +1,319 @@
+---
+argument-hint: [plan-ID] [task-ID]
+description: Execute a single task with dependency validation and status management
+---
+# Single Task Execution
+
+You are responsible for executing a single task within a plan while maintaining strict dependency validation and proper status management. Your role is to ensure the task is ready for execution, deploy the appropriate agent, and track execution progress.
+
+## Critical Rules
+
+1. **Never skip dependency validation** - Task execution requires all dependencies to be completed
+2. **Validate task status** - Never execute tasks that are already completed or in-progress
+3. **Maintain status integrity** - Update task status throughout the execution lifecycle
+4. **Use appropriate agents** - Match task skills to available sub-agents
+5. **Document execution** - Record all outcomes and issues encountered
+
+## Input Requirements
+- Plan ID: $1 (required)
+- Task ID: $2 (required)
+- Task management directory structure: `@.ai/task-manager/`
+- Dependency checking script: `@templates/ai-task-manager/config/scripts/check-task-dependencies.sh`
+
+### Input Validation
+
+First, validate that both arguments are provided:
+
+```bash
+if [ -z "$1" ] || [ -z "$2" ]; then
+    echo "Error: Both plan ID and task ID are required"
+    echo "Usage: /tasks:execute-task [plan-ID] [task-ID]"
+    echo "Example: /tasks:execute-task 16 03"
+    exit 1
+fi
+```
+
+## Execution Process
+
+### 1. Plan and Task Location
+
+Locate the plan directory using the established find pattern:
+
+```bash
+PLAN_ID="$1"
+TASK_ID="$2"
+
+# Find plan directory
+PLAN_DIR=$(find .ai/task-manager/{plans,archive} -type d -name "${PLAN_ID}--*" 2>/dev/null | head -1)
+
+if [ -z "$PLAN_DIR" ]; then
+    echo "Error: Plan with ID ${PLAN_ID} not found"
+    echo "Available plans:"
+    find .ai/task-manager/plans -name "*--*" -type d | head -5
+    exit 1
+fi
+
+echo "Found plan: $PLAN_DIR"
+```
+
+### 2. Task File Validation
+
+Locate and validate the specific task file:
+
+```bash
+# Handle both padded (01, 02) and unpadded (1, 2) task IDs
+TASK_FILE=""
+if [ -f "${PLAN_DIR}/tasks/${TASK_ID}--"*.md ]; then
+    TASK_FILE=$(ls "${PLAN_DIR}/tasks/${TASK_ID}--"*.md 2>/dev/null | head -1)
+elif [ -f "${PLAN_DIR}/tasks/0${TASK_ID}--"*.md ]; then
+    TASK_FILE=$(ls "${PLAN_DIR}/tasks/0${TASK_ID}--"*.md 2>/dev/null | head -1)
+fi
+
+if [ -z "$TASK_FILE" ] || [ ! -f "$TASK_FILE" ]; then
+    echo "Error: Task with ID ${TASK_ID} not found in plan ${PLAN_ID}"
+    echo "Available tasks in plan:"
+    find "$PLAN_DIR/tasks" -name "*.md" -type f | head -5
+    exit 1
+fi
+
+echo "Found task: $(basename "$TASK_FILE")"
+```
+
+### 3. Task Status Validation
+
+Check current task status to ensure it can be executed:
+
+```bash
+# Extract current status from task frontmatter
+CURRENT_STATUS=$(awk '
+    /^---$/ { if (++delim == 2) exit }
+    /^status:/ {
+        gsub(/^status:[ \t]*/, "")
+        gsub(/^["'\'']/, "")
+        gsub(/["'\'']$/, "")
+        print
+        exit
+    }
+' "$TASK_FILE")
+
+echo "Current task status: ${CURRENT_STATUS:-unknown}"
+
+# Validate status allows execution
+case "$CURRENT_STATUS" in
+    "completed")
+        echo "Error: Task ${TASK_ID} is already completed"
+        echo "Use execute-blueprint to re-execute the entire plan if needed"
+        exit 1
+        ;;
+    "in-progress")
+        echo "Error: Task ${TASK_ID} is already in progress"
+        echo "Wait for current execution to complete or check for stale processes"
+        exit 1
+        ;;
+    "pending"|"failed"|"")
+        echo "Task status allows execution - proceeding..."
+        ;;
+    *)
+        echo "Warning: Unknown task status '${CURRENT_STATUS}' - proceeding with caution..."
+        ;;
+esac
+```
+
+### 4. Dependency Validation
+
+Use the dependency checking script to validate all dependencies:
+
+```bash
+# Call the dependency checking script
+if ! @templates/ai-task-manager/config/scripts/check-task-dependencies.sh "$PLAN_ID" "$TASK_ID"; then
+    echo ""
+    echo "Task execution blocked by unresolved dependencies."
+    echo "Please complete the required dependencies first."
+    exit 1
+fi
+
+echo ""
+echo "✓ All dependencies resolved - proceeding with execution"
+```
+
+### 5. Agent Selection
+
+Read task skills and select appropriate task-specific agent:
+
+```bash
+# Extract skills from task frontmatter
+TASK_SKILLS=$(awk '
+    /^---$/ { if (++delim == 2) exit }
+    /^skills:/ {
+        in_skills = 1
+        # Check if skills are on the same line
+        if (match($0, /\[.*\]/)) {
+            gsub(/^skills:[ \t]*\[/, "")
+            gsub(/\].*$/, "")
+            gsub(/[ \t]/, "")
+            print
+            in_skills = 0
+        }
+        next
+    }
+    in_skills && /^[^ ]/ { in_skills = 0 }
+    in_skills && /^[ \t]*-/ {
+        gsub(/^[ \t]*-[ \t]*/, "")
+        gsub(/^"/, ""); gsub(/"$/, "")
+        print
+    }
+' "$TASK_FILE" | tr ',' '\n' | sed 's/^[ \t]*//;s/[ \t]*$//' | grep -v '^$')
+
+echo "Task skills required: $TASK_SKILLS"
+
+# Check for available sub-agents across assistant directories
+AGENT_FOUND=false
+for assistant_dir in .claude .gemini .opencode; do
+    if [ -d "$assistant_dir/agents" ] && [ -n "$(ls $assistant_dir/agents 2>/dev/null)" ]; then
+        echo "Available sub-agents detected in $assistant_dir - will match to task requirements"
+        AGENT_FOUND=true
+        break
+    fi
+done
+
+if [ "$AGENT_FOUND" = false ]; then
+    echo "Using general-purpose agent for task execution"
+fi
+```
+
+### 6. Status Update to In-Progress
+
+Update task status before execution:
+
+```bash
+echo "Updating task status to in-progress..."
+
+# Create temporary file with updated status
+TEMP_FILE=$(mktemp)
+awk '
+    /^---$/ {
+        if (++delim == 1) {
+            print
+            next
+        } else if (delim == 2) {
+            print "status: \"in-progress\""
+            print
+            next
+        }
+    }
+    /^status:/ && delim == 1 {
+        print "status: \"in-progress\""
+        next
+    }
+    { print }
+' "$TASK_FILE" > "$TEMP_FILE"
+
+# Replace original file
+mv "$TEMP_FILE" "$TASK_FILE"
+
+echo "✓ Task status updated to in-progress"
+```
+
+### 7. Task Execution
+
+Deploy the task using the Task tool with full context:
+
+**Task Deployment**: Use your internal Task tool to execute the task with the following context:
+- Task file path: `$TASK_FILE`
+- Plan directory: `$PLAN_DIR`
+- Required skills: `$TASK_SKILLS`
+- Agent selection: Based on skills analysis or general-purpose agent
+
+Read the complete task file and execute according to its requirements. The task includes:
+- Objective and acceptance criteria
+- Technical requirements and implementation notes
+- Input dependencies and expected output artifacts
+
+### 8. Post-Execution Status Management
+
+After task completion, update the status based on execution outcome:
+
+```bash
+TEMP_FILE=$(mktemp)
+awk '
+    /^---$/ {
+        if (++delim == 1) {
+            print
+            next
+        } else if (delim == 2) {
+            print "status: \"completed\""
+            print
+            next
+        }
+    }
+    /^status:/ && delim == 1 {
+        print "status: \"completed\""
+        next
+    }
+    { print }
+' "$TASK_FILE" > "$TEMP_FILE"
+
+mv "$TEMP_FILE" "$TASK_FILE"
+
+echo "✓ Task ${TASK_ID} completed successfully"
+echo ""
+echo "You can now execute dependent tasks or continue with the full blueprint execution."
+```
+
+## Error Handling
+
+If task execution fails:
+
+```bash
+# On execution failure, update status to failed
+echo "Task execution failed - updating status..."
+
+TEMP_FILE=$(mktemp)
+awk '
+    /^---$/ {
+        if (++delim == 1) {
+            print
+            next
+        } else if (delim == 2) {
+            print "status: \"failed\""
+            print
+            next
+        }
+    }
+    /^status:/ && delim == 1 {
+        print "status: \"failed\""
+        next
+    }
+    { print }
+' "$TASK_FILE" > "$TEMP_FILE"
+
+mv "$TEMP_FILE" "$TASK_FILE"
+
+echo "Task ${TASK_ID} marked as failed"
+echo "Check the task requirements and try again"
+exit 1
+```
+
+## Usage Examples
+
+```bash
+# Execute a specific task
+/tasks:execute-task 16 1
+
+# Execute task with zero-padded ID
+/tasks:execute-task 16 03
+
+# Execute task from archived plan
+/tasks:execute-task 12 05
+```
+
+## Integration Notes
+
+This command integrates with the existing task management system by:
+- Using established plan and task location patterns
+- Leveraging the dependency checking script for validation
+- Following status management conventions
+- Maintaining compatibility with execute-blueprint workflows
+- Preserving task isolation and dependency order
+
+The command complements execute-blueprint by providing granular task control while maintaining the same validation and execution standards.

package/templates/{commands → assistant/commands}/tasks/generate-tasks.md

@@ -5,14 +5,14 @@ description: Generate tasks to implement the plan with the provided ID.
 # Comprehensive Task List Creation
 You are a comprehensive task planning assistant. Your role is to create detailed, actionable plans based on user input while ensuring you have all necessary context before proceeding.
 
-Include @.ai/task-manager/TASK_MANAGER_INFO.md for the directory structure of tasks.
+Include @.ai/task-manager/TASK_MANAGER.md for the directory structure of tasks.
 
 ## Instructions
 
 You will think hard to analyze the provided plan document and decompose it into atomic, actionable tasks with clear dependencies and groupings.
 
 ### Input
-- A plan document. See @.ai/task-manager/TASK_MANAGER_INFO.md fo find the plan with ID $1
+- A plan document. See @.ai/task-manager/TASK_MANAGER.md fo find the plan with ID $1
 - The plan contains high-level objectives and implementation steps
 
 ### Input Error Handling
@@ -118,6 +118,7 @@ Tests that verify custom business logic, critical paths, and edge cases specific
 5. Ensure no task requires multiple skill sets
 6. Verify each task has clear inputs and outputs
 7. **Minimize test tasks**: Combine related testing scenarios, avoid testing framework functionality
+8. Be very detailed with the "Implementation Notes". This should contain enough detail for a non-thinking LLM model to successfully complete the task. Put these instructions in a collapsible field `<details>`.
 
 #### Step 2: Dependency Analysis
 For each task, identify:
@@ -130,8 +131,9 @@ Dependency Rule: Task B depends on Task A if:
 - B modifies code created by A
 - B tests functionality implemented in A
 
-#### Step 3: Task Grouping
-Organize tasks into logical groups based on feature areas (e.g., "user-authentication", "payment-processing", "dashboard", "reporting", "notifications")
+#### Step 3: POST_TASK_GENERATION_ALL hook
+
+Read and run the @.ai/task-manager/config/hooks/POST_TASK_GENERATION_ALL.md
 
 #### Step 4: Output Generation
 
@@ -146,6 +148,9 @@ dependencies: []  # List of task IDs, e.g., [2, 3]
 status: "pending"  # pending | in-progress | completed | needs-clarification
 created: "2024-01-15"
 skills: ["react-components", "authentication"]  # Technical skills required for this task
+# Optional: Include complexity scores for high-complexity tasks or decomposition tracking
+# complexity_score: 4.2  # Composite complexity score (only if >4 or decomposed)
+# complexity_notes: "Decomposed from original task due to high technical depth"
 ---
 ```
 
@@ -189,6 +194,16 @@ The schema for this frontmatter is:
       },
       "minItems": 1,
       "uniqueItems": true
+    },
+    "complexity_score": {
+      "type": "number",
+      "minimum": 1,
+      "maximum": 10,
+      "description": "Optional: Composite complexity score (include only if >4 or for decomposed tasks)"
+    },
+    "complexity_notes": {
+      "type": "string",
+      "description": "Optional: Rationale for complexity score or decomposition decisions"
     }
   },
   "additionalProperties": false
@@ -196,32 +211,8 @@ The schema for this frontmatter is:
 ```
 
 ##### Task Body Structure
-```markdown
-## Objective
-[Clear statement of what this task accomplishes]
-
-## Skills Required
-[Reference to the skills listed in frontmatter - these should align with the technical work needed]
-
-## Acceptance Criteria
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
 
-Use your internal TODO tool to track these and keep on track.
-
-## Technical Requirements
-[Specific technical details, APIs, libraries, etc. - use this to infer appropriate skills]
-
-## Input Dependencies
-[What artifacts/code from other tasks are needed]
-
-## Output Artifacts
-[What this task produces for other tasks to consume]
-
-## Implementation Notes
-[Any helpful context or suggestions, including skill-specific guidance]
-```
+Use the task template in @.ai/task-manager/config/templates/TASK_TEMPLATE.md
 
 ### Task ID Generation
 
@@ -311,6 +302,8 @@ If the command fails or returns unexpected results:
 
 ### Validation Checklist
 Before finalizing, ensure:
+
+**Core Task Requirements:**
 - [ ] Each task has 1-2 appropriate technical skills assigned
 - [ ] Skills are automatically inferred from task objectives and technical requirements
 - [ ] All dependencies form an acyclic graph
@@ -318,10 +311,36 @@ Before finalizing, ensure:
 - [ ] Groups are consistent and meaningful
 - [ ] Every **explicitly stated** task from the plan is covered
 - [ ] No redundant or overlapping tasks
-- [ ] **Minimization applied**: Each task is absolutely necessary
-- [ ] **Test tasks are meaningful**: Focus on business logic, not framework functionality
-- [ ] **No gold-plating**: Only plan requirements are addressed
-- [ ] Total task count represents minimum viable implementation
+
+**Complexity Analysis & Controls:**
+- [ ] **Complexity Analysis Complete**: All tasks assessed using 5-dimension scoring
+- [ ] **Decomposition Applied**: Tasks with composite score ≥6 have been decomposed or justified
+- [ ] **Final Task Complexity**: All final tasks have composite score ≤5 (target ≤4)
+- [ ] **Iteration Limits Respected**: No task exceeded 3 decomposition rounds
+- [ ] **Minimum Viability**: No tasks decomposed below complexity threshold of 3
+- [ ] **Quality Gates Passed**: All decomposed tasks meet enhanced quality criteria
+- [ ] **Dependency Integrity**: No circular dependencies or orphaned tasks exist
+- [ ] **Error Handling Complete**: All edge cases resolved or escalated appropriately
+
+**Complexity Documentation Requirements:**
+- [ ] **Complexity Scores Documented**: Individual dimension scores recorded for complex tasks
+- [ ] **Decomposition History**: Iteration tracking included in `complexity_notes` for decomposed tasks
+- [ ] **Validation Status**: All tasks marked with appropriate validation outcomes
+- [ ] **Escalation Documentation**: High-complexity tasks have clear escalation notes
+- [ ] **Consistency Validated**: Complexity scores align with task descriptions and skills
+
+**Scope & Quality Control:**
+- [ ] **Minimization Applied**: Each task is absolutely necessary (20-30% reduction target)
+- [ ] **Test Tasks are Meaningful**: Focus on business logic, not framework functionality
+- [ ] **No Gold-plating**: Only plan requirements are addressed
+- [ ] **Total Task Count**: Represents minimum viable implementation
+- [ ] **Scope Preservation**: Decomposed tasks collectively match original requirements
+
+**System Reliability:**
+- [ ] **Error Conditions Resolved**: No unresolved error states remain
+- [ ] **Manual Intervention Flagged**: Complex edge cases properly escalated
+- [ ] **Quality Checkpoints**: All validation gates completed successfully
+- [ ] **Dependency Graph Validated**: Full dependency analysis confirms acyclic, logical relationships
 
 ### Error Handling
 If the plan lacks sufficient detail:
@@ -367,7 +386,7 @@ The execution blueprint organizes tasks into sequential phases where:
 ## Execution Blueprint
 
 **Validation Gates:**
-- Reference: `@.ai/task-manager/VALIDATION_GATES.md`
+- Reference: `@.ai/task-manager/config/hooks/POST_PHASE.md`
 
 ### Phase 1: [Descriptive Phase Name]
 **Parallel Tasks:**
@@ -396,7 +415,7 @@ The execution blueprint organizes tasks into sequential phases where:
 
 #### Phase Transition Rules
 1. All tasks in the current phase must have status: "completed"
-2. All validation gates defined in `@.ai/task-manager/VALIDATION_GATES.md` for the current phase must pass
+2. All validation gates defined in `@.ai/task-manager/config/hooks/POST_PHASE.md` for the current phase must pass
 3. No task in a future phase can begin until these conditions are met
 
 #### Blueprint Verification