@e0ipso/ai-task-manager 1.2.1 → 1.4.0

package/templates/ai-task-manager/config/hooks/POST_TASK_GENERATION_ALL.md

@@ -0,0 +1,96 @@
+[Post-task generation validation and refinement]
+
+## Step 3.1: Complexity Analysis & Refinement
+
+### Complexity Scoring Matrix (1-10 scale)
+
+| Dimension | 1-2 | 3-4 | 5-6 | 7-8 | 9-10 |
+|-----------|-----|-----|-----|-----|------|
+| **Technical** | Basic ops | Single tech | 2-3 techs | Multiple complex | Cutting-edge |
+| **Decision** | No decisions | 1-2 minor | Trade-offs | Interdependent | Novel solutions |
+| **Integration** | Single file | 2-3 files | Multi-module | Many systems | 15+ services |
+| **Scope** | Atomic action | Small feature | Complete feature | Major feature | Entire subsystem |
+| **Uncertainty** | Crystal clear | Minor ambiguity | Some clarification | Research required | Experimental |
+
+**Composite Score** = MAX(Technical×1.0, Decision×0.9, Integration×0.8, Scope×0.7, Uncertainty×1.1)
+
+### Decomposition Rules
+
+**Thresholds:**
+- Composite ≥6: Consider decomposition
+- Any dimension ≥8: Mandatory decomposition
+- Multiple dimensions ≥6: High priority
+
+**Patterns by Driver:**
+| Driver | Pattern | Strategy |
+|--------|---------|----------|
+| Technical | Technology Layering | Split by tech boundaries |
+| Decision | Decision-Implementation | Separate analysis from execution |
+| Integration | Integration Isolation | Core feature + integrations |
+| Scope | Functional | Split by user workflows |
+| Uncertainty | Research-Implementation | Prototype then implement |
+
+### AIDVR Process
+1. **Assess**: Confirm need (score >5)
+2. **Identify**: Find natural breakpoints
+3. **Decompose**: Apply pattern
+4. **Validate**: Check criteria
+5. **Reconstruct**: Update dependencies
+
+### Safety Controls
+
+**Limits:**
+- Max 3 decomposition rounds per task
+- No decomposition if score ≤3
+- Min 2-hour work per subtask
+- Stop if complexity not decreasing
+
+**Stop Conditions:**
+1. Atomic boundary reached
+2. <1 skill per subtask
+3. Overhead > benefit
+4. Resource fragmentation
+5. <2 hour granularity
+6. 3 iterations reached
+7. Score ≤3
+8. No complexity reduction
+
+### Validation Checklist
+
+**Per Subtask:**
+- [ ] Complexity ≤5 (target ≤4)
+- [ ] Skills ≤2
+- [ ] Clear acceptance criteria
+- [ ] Dependencies acyclic
+- [ ] Score ≥2 (min viability)
+
+**Decomposition Quality:**
+- [ ] Coverage: All requirements included
+- [ ] Coherence: Single purpose per task
+- [ ] Consistency: Lower scores than parent
+- [ ] Coordination: Integration plan exists
+
+### Error Handling
+
+| Issue | Detection | Resolution |
+|-------|-----------|------------|
+| Infinite loop | No reduction after 2 rounds | Stop, mark needs-clarification |
+| Circular dependency | Task reaches itself | Break shortest cycle |
+| Over-decomposition | Score <2 or <2hrs | Merge with sibling |
+| Orphaned task | Missing dependencies | Create or remove dependency |
+| Scope creep | Subtasks > original | Remove excess scope |
+| Skill conflicts | >2 skills needed | Decompose by skill boundary |
+| High complexity | >7 after max rounds | Escalate with documentation |
+
+### Documentation Format
+
+In `complexity_notes`:
+```
+Original: 8.2 → Round 1 → [4.1, 3.8, 4.5] → PASSED
+```
+
+**Quality Gates Before Proceeding:**
+- All tasks ≤5 complexity or escalated
+- No unresolved errors
+- Iterations documented
+- Validation complete

package/templates/ai-task-manager/config/scripts/check-task-dependencies.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+
+# Script: check-task-dependencies.sh
+# Purpose: Check if a task has all of its dependencies resolved (completed)
+# Usage: ./check-task-dependencies.sh <plan-id> <task-id>
+# Returns: 0 if all dependencies are resolved, 1 if not
+
+set -e
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_error() {
+    echo -e "${RED}ERROR: $1${NC}" >&2
+}
+
+print_success() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠ $1${NC}"
+}
+
+print_info() {
+    echo -e "$1"
+}
+
+# Check arguments
+if [ $# -ne 2 ]; then
+    print_error "Invalid number of arguments"
+    echo "Usage: $0 <plan-id> <task-id>"
+    echo "Example: $0 16 03"
+    exit 1
+fi
+
+PLAN_ID="$1"
+TASK_ID="$2"
+
+# Find the 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
+    print_error "Plan with ID ${PLAN_ID} not found"
+    exit 1
+fi
+
+print_info "Found plan directory: ${PLAN_DIR}"
+
+# Construct task file path
+# 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
+    # Try with zero-padding if direct match fails
+    TASK_FILE=$(ls "${PLAN_DIR}/tasks/0${TASK_ID}--"*.md 2>/dev/null | head -1)
+fi
+
+if [ -z "$TASK_FILE" ] || [ ! -f "$TASK_FILE" ]; then
+    print_error "Task with ID ${TASK_ID} not found in plan ${PLAN_ID}"
+    exit 1
+fi
+
+print_info "Checking task: $(basename "$TASK_FILE")"
+echo ""
+
+# Extract dependencies from task frontmatter
+# Using awk to parse YAML frontmatter
+DEPENDENCIES=$(awk '
+    /^---$/ { if (++delim == 2) exit }
+    /^dependencies:/ {
+        dep_section = 1
+        # Check if dependencies are on the same line
+        if (match($0, /\[.*\]/)) {
+            gsub(/^dependencies:[ \t]*\[/, "")
+            gsub(/\].*$/, "")
+            gsub(/[ \t]/, "")
+            print
+            dep_section = 0
+        }
+        next
+    }
+    dep_section && /^[^ ]/ { dep_section = 0 }
+    dep_section && /^[ \t]*-/ {
+        gsub(/^[ \t]*-[ \t]*/, "")
+        gsub(/[ \t]*$/, "")
+        print
+    }
+' "$TASK_FILE" | tr ',' '\n' | sed 's/^[ \t]*//;s/[ \t]*$//' | grep -v '^$')
+
+# Check if there are any dependencies
+if [ -z "$DEPENDENCIES" ]; then
+    print_success "Task has no dependencies - ready to execute!"
+    exit 0
+fi
+
+# Display dependencies
+print_info "Task dependencies found:"
+echo "$DEPENDENCIES" | while read -r dep; do
+    echo "  - Task ${dep}"
+done
+echo ""
+
+# Check each dependency
+ALL_RESOLVED=true
+UNRESOLVED_DEPS=""
+RESOLVED_COUNT=0
+TOTAL_DEPS=$(echo "$DEPENDENCIES" | wc -l)
+
+print_info "Checking dependency status..."
+echo ""
+
+for DEP_ID in $DEPENDENCIES; do
+    # Find dependency task file
+    DEP_FILE=""
+
+    # Try exact match first
+    if [ -f "${PLAN_DIR}/tasks/${DEP_ID}--"*.md ]; then
+        DEP_FILE=$(ls "${PLAN_DIR}/tasks/${DEP_ID}--"*.md 2>/dev/null | head -1)
+    elif [ -f "${PLAN_DIR}/tasks/0${DEP_ID}--"*.md ]; then
+        # Try with zero-padding
+        DEP_FILE=$(ls "${PLAN_DIR}/tasks/0${DEP_ID}--"*.md 2>/dev/null | head -1)
+    else
+        # Try removing potential zero-padding from DEP_ID
+        UNPADDED_DEP=$(echo "$DEP_ID" | sed 's/^0*//')
+        if [ -f "${PLAN_DIR}/tasks/${UNPADDED_DEP}--"*.md ]; then
+            DEP_FILE=$(ls "${PLAN_DIR}/tasks/${UNPADDED_DEP}--"*.md 2>/dev/null | head -1)
+        elif [ -f "${PLAN_DIR}/tasks/0${UNPADDED_DEP}--"*.md ]; then
+            DEP_FILE=$(ls "${PLAN_DIR}/tasks/0${UNPADDED_DEP}--"*.md 2>/dev/null | head -1)
+        fi
+    fi
+
+    if [ -z "$DEP_FILE" ] || [ ! -f "$DEP_FILE" ]; then
+        print_error "Dependency task ${DEP_ID} not found"
+        ALL_RESOLVED=false
+        UNRESOLVED_DEPS="${UNRESOLVED_DEPS}${DEP_ID} (not found)\n"
+        continue
+    fi
+
+    # Extract status from dependency task
+    STATUS=$(awk '
+        /^---$/ { if (++delim == 2) exit }
+        /^status:/ {
+            gsub(/^status:[ \t]*/, "")
+            gsub(/^["'\'']/, "")
+            gsub(/["'\'']$/, "")
+            print
+            exit
+        }
+    ' "$DEP_FILE")
+
+    # Check if status is completed
+    if [ "$STATUS" = "completed" ]; then
+        print_success "Task ${DEP_ID} - Status: completed ✓"
+        ((RESOLVED_COUNT++))
+    else
+        print_warning "Task ${DEP_ID} - Status: ${STATUS:-unknown} ✗"
+        ALL_RESOLVED=false
+        UNRESOLVED_DEPS="${UNRESOLVED_DEPS}${DEP_ID} (${STATUS:-unknown})\n"
+    fi
+done
+
+echo ""
+print_info "========================================="
+print_info "Dependency Check Summary"
+print_info "========================================="
+print_info "Total dependencies: ${TOTAL_DEPS}"
+print_info "Resolved: ${RESOLVED_COUNT}"
+print_info "Unresolved: $((TOTAL_DEPS - RESOLVED_COUNT))"
+echo ""
+
+if [ "$ALL_RESOLVED" = true ]; then
+    print_success "All dependencies are resolved! Task ${TASK_ID} is ready to execute."
+    exit 0
+else
+    print_error "Task ${TASK_ID} has unresolved dependencies:"
+    echo -e "$UNRESOLVED_DEPS"
+    print_info "Please complete the dependencies before executing this task."
+    exit 1
+fi

package/templates/ai-task-manager/config/templates/PLAN_TEMPLATE.md

@@ -0,0 +1,93 @@
+---
+id: [PLAN-ID]
+summary: "[Brief one-line description of what this plan accomplishes]"
+created: [YYYY-MM-DD]
+---
+
+# Plan: [Descriptive Plan Title]
+
+## Original Work Order
+[The unmodified user input that was used to generate this plan, as a quote]
+
+## Plan Clarifications [only add it if clarifications were necessary]
+[Clarification questions and answers in table format]
+
+## Executive Summary
+
+[Provide a 2-3 paragraph overview of the plan. Include:
+- What the plan accomplishes
+- Why this approach was chosen
+- Key benefits and outcomes expected]
+
+## Context
+
+### Current State
+[Describe the existing situation, problems, or gaps that this plan addresses. Include specific details about what exists now, current limitations, and why change is needed.]
+
+### Target State
+[Describe the desired end state after plan completion. Be specific about the expected outcomes and how success will be measured.]
+
+### Background
+[Any additional context, requirements, constraints, any solutions that we tried that didn't work, or relevant history that informs the implementation approach.]
+
+## Technical Implementation Approach
+
+[Provide an overview of the implementation strategy, key architectural decisions, and technical approach. Break down into major components or phases using ### subheadings.]
+
+### [Component/Phase 1 Name]
+**Objective**: [What this component accomplishes and why it's important]
+
+[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
+
+### [Component/Phase 2 Name]
+**Objective**: [What this component accomplishes and why it's important]
+
+[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
+
+### [Additional Components as Needed]
+[Continue with additional technical components or phases following the same pattern]
+
+## Risk Considerations and Mitigation Strategies
+
+### Technical Risks
+- **[Specific Technical Risk]**: [Description of the technical challenge or limitation]
+    - **Mitigation**: [Specific strategy to address this technical risk]
+
+### Implementation Risks
+- **[Specific Implementation Risk]**: [Description of implementation-related challenge]
+    - **Mitigation**: [Specific strategy to address this implementation risk]
+
+### [Additional Risk Categories as Needed]
+[Continue with other risk categories such as Integration Risks, Quality Risks, Resource Risks, etc.]
+
+## Success Criteria
+
+### Primary Success Criteria
+1. [Measurable outcome 1]
+2. [Measurable outcome 2]
+3. [Measurable outcome 3]
+
+### Quality Assurance Metrics
+1. [Quality measure 1]
+2. [Quality measure 2]
+3. [Quality measure 3]
+
+## Resource Requirements
+
+### Development Skills
+[Required technical expertise and specialized knowledge areas needed for successful implementation]
+
+### Technical Infrastructure
+[Tools, libraries, frameworks, and systems needed for development and deployment]
+
+### [Additional Resource Categories as Needed]
+[Other resources such as external dependencies, research access, third-party services, etc.]
+
+## Integration Strategy
+[Optional section - how this work integrates with existing systems]
+
+## Implementation Order
+[Optional section - high-level sequence without detailed phases]
+
+## Notes
+[Optional section - any additional considerations, constraints, or important context]

package/templates/ai-task-manager/config/templates/TASK_TEMPLATE.md

@@ -0,0 +1,36 @@
+---
+id: [TASK-ID]
+group: "user-authentication"
+dependencies: []  # List of task IDs, e.g., [2, 3]
+status: "[STATUS]"  # pending | in-progress | completed | needs-clarification
+created: [YYYY-MM-DD]
+skills: # Technical skills required for this task
+  - [SKILL-1]
+  - [SKILL-2]
+---
+# [TASK-TITLE]
+
+## 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]

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

@@ -6,7 +6,7 @@ description: Create a comprehensive plan to accomplish the request from the user
 
 You are a comprehensive task planning assistant. Your role is to think hard 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/config/TASK_MANAGER.md for the directory structure of tasks.
 
 ## Instructions
 
@@ -94,107 +94,13 @@ Remember that a plan needs to be reviewed by a human. Be concise and to the poin
 ### Output Format
 Structure your response as follows:
 - If context is insufficient: List specific clarifying questions
-- If context is sufficient: Provide the comprehensive plan using the structure above. Use the information in @TASK_MANAGER_INFO.md for the directory structure and additional information about plans.
+- If context is sufficient: Provide the comprehensive plan using the structure above. Use the information in @TASK_MANAGER.md for the directory structure and additional information about plans.
 
 Outside the plan document, be **extremely** concise. Just tell the user that you are done, and instruct them to review the plan document.
 
 #### Plan Template
 
-```markdown
----
-id: [PLAN-ID]
-summary: "[Brief one-line description of what this plan accomplishes]"
-created: [YYYY-MM-DD]
----
-
-# Plan: [Descriptive Plan Title]
-
-## Original Work Order
-[The unmodified user input that was used to generate this plan, as a quote]
-
-## Plan Clarifications [only add it if clarifications were necessary]
-[Clarification questions and answers in table format]
-
-## Executive Summary
-
-[Provide a 2-3 paragraph overview of the plan. Include:
-- What the plan accomplishes
-- Why this approach was chosen
-- Key benefits and outcomes expected]
-
-## Context
-
-### Current State
-[Describe the existing situation, problems, or gaps that this plan addresses. Include specific details about what exists now, current limitations, and why change is needed.]
-
-### Target State
-[Describe the desired end state after plan completion. Be specific about the expected outcomes and how success will be measured.]
-
-### Background
-[Any additional context, requirements, constraints, any solutions that we tried that didn't work, or relevant history that informs the implementation approach.]
-
-## Technical Implementation Approach
-
-[Provide an overview of the implementation strategy, key architectural decisions, and technical approach. Break down into major components or phases using ### subheadings.]
-
-### [Component/Phase 1 Name]
-**Objective**: [What this component accomplishes and why it's important]
-
-[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
-
-### [Component/Phase 2 Name]
-**Objective**: [What this component accomplishes and why it's important]
-
-[Detailed explanation of implementation approach, key technical decisions, specifications, and rationale for design choices.]
-
-### [Additional Components as Needed]
-[Continue with additional technical components or phases following the same pattern]
-
-## Risk Considerations and Mitigation Strategies
-
-### Technical Risks
-- **[Specific Technical Risk]**: [Description of the technical challenge or limitation]
-  - **Mitigation**: [Specific strategy to address this technical risk]
-
-### Implementation Risks
-- **[Specific Implementation Risk]**: [Description of implementation-related challenge]
-  - **Mitigation**: [Specific strategy to address this implementation risk]
-
-### [Additional Risk Categories as Needed]
-[Continue with other risk categories such as Integration Risks, Quality Risks, Resource Risks, etc.]
-
-## Success Criteria
-
-### Primary Success Criteria
-1. [Measurable outcome 1]
-2. [Measurable outcome 2]
-3. [Measurable outcome 3]
-
-### Quality Assurance Metrics
-1. [Quality measure 1]
-2. [Quality measure 2]
-3. [Quality measure 3]
-
-## Resource Requirements
-
-### Development Skills
-[Required technical expertise and specialized knowledge areas needed for successful implementation]
-
-### Technical Infrastructure
-[Tools, libraries, frameworks, and systems needed for development and deployment]
-
-### [Additional Resource Categories as Needed]
-[Other resources such as external dependencies, research access, third-party services, etc.]
-
-## Integration Strategy
-[Optional section - how this work integrates with existing systems]
-
-## Implementation Order
-[Optional section - high-level sequence without detailed phases]
-
-## Notes
-[Optional section - any additional considerations, constraints, or important context]
-```
+Use the template in @.ai/task-manager/config/templates/PLAN_TEMPLATE.md
 
 #### Patterns to Avoid
 Do not include the following in your plan output.

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

@@ -15,9 +15,9 @@ You are the orchestrator responsible for executing all tasks defined in the exec
 5. **Fail safely** - Better to halt and request help than corrupt the execution state
 
 ## Input Requirements
-- A plan document with an execution blueprint section. See @.ai/task-manager/TASK_MANAGER_INFO.md fo find the plan with ID $1
+- A plan document with an execution blueprint section. See @.ai/task-manager/TASK_MANAGER.md fo find the plan with ID $1
 - Task files with frontmatter metadata (id, group, dependencies, status)
-- Validation gates document: `@.ai/task-manager/VALIDATION_GATES.md`
+- Validation gates document: `@.ai/task-manager/config/hooks/POST_PHASE.md`
 
 ### Input Error Handling
 If the plan does not exist, or the plan does not have an execution blueprint section. Stop immediately and show an error to the user.
@@ -26,14 +26,24 @@ If the plan does not exist, or the plan does not have an execution blueprint sec
 
 ### Phase Pre-Execution
 
-Before starting execution check if you are in the `main` branch. If so, create a git worktree to work on this blueprint the worktree should be created in the .ai/task-manager/worktrees folder.
+Before starting execution check if you are in the `main` branch. If so, create a git branch to work on this blueprint use the plan name for the branch name.
 
 ### Phase Execution Workflow
 
 1. **Phase Initialization**
     - Identify current phase from the execution blueprint
     - List all tasks scheduled for parallel execution in this phase
-    - Verify all task dependencies from previous phases are marked "completed"
+    - **Validate Task Dependencies**: For each task in the current phase, use the dependency checking script:
+        ```bash
+        # For each task in current phase
+        for TASK_ID in $PHASE_TASKS; do
+            if ! @templates/ai-task-manager/config/scripts/check-task-dependencies.sh "$1" "$TASK_ID"; then
+                echo "ERROR: Task $TASK_ID has unresolved dependencies - cannot proceed with phase execution"
+                echo "Please resolve dependencies before continuing with blueprint execution"
+                exit 1
+            fi
+        done
+        ```
     - Confirm no tasks are marked "needs-clarification"
     - If any phases are marked as completed, verify they are actually completed and continue from the next phase.
 
@@ -57,7 +67,7 @@ Before starting execution check if you are in the `main` branch. If so, create a
     - Document any issues or exceptions encountered
 
 5. **Validation Gate Execution**
-    - Reference validation criteria from `@.ai/task-manager/VALIDATION_GATES.md`
+    - Reference validation criteria from `@.ai/task-manager/config/hooks/POST_PHASE.md`
     - Execute all validation gates for the current phase
     - Document validation results
     - Only proceed if ALL validations pass
@@ -69,8 +79,8 @@ Before starting execution check if you are in the `main` branch. If so, create a
 
 ### Agent Selection Guidelines
 
-#### Available Claude Code Sub-Agents
-Analyze the sub-agents available under `.claude/agents`. If none are available
+#### Available Sub-Agents
+Analyze the sub-agents available in your current assistant's agents directory. If none are available
 or the available ones do not match the task's requirements, then use a generic
 agent.