# Task Management & Todo Integration System

## Legend
| Symbol | Meaning | | Abbrev | Meaning |
|--------|---------|---|--------|---------|
| 📋 | task/project | | req | requirement |
| ✅ | completed | | impl | implementation |
| 🔄 | in progress | | ctx | context |
| ⏸ | paused | | rec | recovery |

## Two-Tier Architecture

```yaml
Hierarchy:
  Level_1_Tasks: "High-level features (./claudedocs/tasks/ folders)"
    Purpose: "Session persistence, git branching, requirement tracking"
    Scope: "Features spanning multiple sessions"
    Examples: ["build auth system", "implement dashboard", "create API"]
    
  Level_2_Todos: "Immediate actionable steps (TodoWrite/TodoRead)"
    Purpose: "Context switching, progress tracking, focus management"
    Scope: "Small chunks within current session"
    Examples: ["create user model", "add login endpoint", "write tests"]

Integration_Principle:
  - Tasks provide persistence across sessions
  - Todos provide focus within sessions
  - Both work together seamlessly
  - No duplication, clear boundaries
  - Automatic synchronization between layers
```

## Automatic Task Detection

```yaml
Complexity_Analysis_Engine:
  Keyword_Extraction:
    Trigger_Verbs: ["build", "create", "implement", "develop", "design", "add", "integrate"]
    Scope_Nouns: ["system", "feature", "functionality", "component", "service", "application"]
    Complexity_Flags: ["authentication", "database", "API", "full-stack", "architecture", "integration"]
    
  Scoring_System:
    Base_Score: 0
    Trigger_Verb: "+2 points each"
    Scope_Noun: "+2 points each"
    Complexity_Flag: "+3 points each"
    Multi_Step_Indicator: "+3 points"
    File_Estimate: "files * 1 point"
    
  Complexity_Thresholds:
    Auto_Create_Task: "≥8 points"
    Brief_Notification: "5-7 points"
    Proceed_Normal: "<5 points"

Pattern_Detection:
  High_Complexity_Patterns:
    - "build a * system"
    - "create * authentication"
    - "implement * database"
    - "develop * application"
    - "full-stack *"
    - "end-to-end *"
    
  Multi_Session_Indicators:
    - "complete *", "entire *", "comprehensive *"
    - Multiple technology mentions
    - Frontend + backend combination
    - Database + API requirements
    - Architecture + implementation scope

Time_Estimation:
  High_Complexity: ">2 hours, likely multiple sessions"
  Medium_Complexity: "1-2 hours, possible session break"
  Low_Complexity: "<1 hour, single session"
  
File_Impact_Assessment:
  High: ">5 estimated files affected"
  Medium: "3-5 files affected"
  Low: "1-2 files affected"
```

## Seamless Auto-Creation Flow

```yaml
Execution_Process:
  Silent_Analysis:
    - Parse requirement in background
    - Calculate complexity score
    - Estimate file impact and time
    - No user interruption during analysis
    
  Instant_Decision:
    Score_8_Plus: "Auto-create immediately, start work"
    Score_5_7: "Brief notification, then create and proceed"
    Score_Under_5: "Use TodoWrite only, no task needed"
    
  Background_Setup:
    - Generate unique task ID (YYYYMMDD-HHMMSS format)
    - Create task file from requirement
    - Setup git branch (task/{id}-{slug})
    - Move to in-progress folder
    - Convert to TodoWrite steps
    - Begin implementation immediately

User_Notification:
  High_Complexity: "[Task created: {id}] {brief_description}"
  Medium_Complexity: "[Multi-step work detected - creating task] {brief_description}"
  Format: "Single line notification only"
  Timing: "After creation, before work begins"
  
No_Interruption_Policy:
  - Never ask "should I create a task?"
  - Never wait for confirmation
  - Never pause workflow for task setup
  - Seamless background operation
  - User only sees brief notification
```

## Workflow Integration

```yaml
Complex_Requirement_Flow:
  1_Auto_Detect: "Complexity ≥8 → create task automatically"
  2_Breakdown: "Task phases → TodoWrite immediate steps"
  3_Execute: "Work on todos → update task progress"
  4_Session_Break: "Preserve both task and todo state"
  5_Resume: "Restore task context + todos on startup"
  
Simple_Requirement_Flow:
  1_Detect: "Complexity <5 → TodoWrite only"
  2_Execute: "Work on todos directly"
  3_Complete: "Mark todos done, no task tracking"
  
Medium_Requirement_Flow:
  1_Detect: "Complexity 5-7 → brief task creation"
  2_Immediate: "Convert to TodoWrite steps"
  3_Execute: "Work on todos with light task tracking"

Task_To_Todos_Conversion:
  When_Task_Starts:
    - Parse task breakdown sections
    - Extract actionable steps
    - Convert to TodoWrite format
    - Preserve task context and ID linkage
    
  Step_Extraction:
    Analysis_Phase: "→ pending todos"
    Implementation_Phase: "→ pending todos"
    Testing_Phase: "→ pending todos"
    Completion_Phase: "→ pending todos"
    
  Todo_Format:
    id: "Auto-generated unique ID"
    content: "Actionable step from task"
    status: "pending"
    priority: "Inherit from parent task"
    task_id: "Link back to parent task"
```

## Task Status Management

```yaml
Status_Transitions:
  pending → in_progress: "/task:start {id} + TodoWrite breakdown"
  in_progress → completed: "All todos complete + /task:complete {id}"
  in_progress → paused: "/task:pause {id} + preserve todos"
  any → cancelled: "/task:cancel {id} + clear todos"
  
Folder_Mapping:
  Pending: "./claudedocs/tasks/pending/"
  In_Progress: "./claudedocs/tasks/in-progress/ + active TodoWrite"
  Completed: "./claudedocs/tasks/completed/ + archived todos"
  Cancelled: "./claudedocs/tasks/cancelled/"

Task_File_Structure:
  Naming: "{type}-{id}-{slug}.md"
  Types: ["feature", "bugfix", "refactor", "docs", "test"]
  ID_Format: "YYYYMMDD-HHMMSS"
  Slug: "kebab-case description"
  
Metadata_Required:
  - id, title, status, priority
  - created, updated timestamps
  - git branch information
  - complexity score
  - estimated completion time
  
Content_Sections:
  - requirement description
  - step-by-step breakdown
  - affected files list
  - context preservation
  - checkpoint history
  - todo integration state
```

## Context Preservation & Recovery

```yaml
Session_State_Tracking:
  Task_Context:
    - Active task ID and current phase
    - Architectural decisions made
    - Git branch and commit info
    - File paths and key variables
    
  Todo_Context:
    - Current todo list state
    - In-progress item details
    - Completed items log
    - Blocking issues identified
    
  Combined_State:
    - Task progress percentage
    - Todo completion ratio
    - Session focus area
    - Next recommended action

Auto_Save_Triggers:
  Context_Threshold: ">70% context capacity full"
  Session_Timeout: ">30min inactive"
  Error_Recovery: "On significant failures"
  Manual_Break: "User requests pause/break"
  
Recovery_On_Startup:
  1_Scan_Tasks: "Check ./claudedocs/tasks/in-progress/"
  2_Restore_Todos: "Rebuild TodoWrite from task state"
  3_Identify_Focus: "Determine current todo and context"
  4_Resume_Message: "Resuming {task} - working on {current_todo}"

Context_Corruption_Handling:
  Task_Exists_No_Todos:
    - Regenerate todos from task breakdown
    - Resume from last known position
    
  Todos_Exist_No_Task:
    - Continue with todos only
    - Warn about missing task context
    
  Both_Missing:
    - Start fresh workflow
    - No recovery needed
    
  Corruption_Recovery:
    - Fallback to task file data
    - Regenerate todos if possible
    - Manual recovery prompts when needed
```

## Smart Synchronization

```yaml
Todo_Completion_Updates_Task:
  On_Todo_Complete:
    - Calculate overall task progress
    - Update task file with progress
    - Move to next logical step
    - Create checkpoint if milestone reached
    
  Progress_Calculation:
    Total_Steps: "Count all todos derived from task"
    Completed_Steps: "Count completed todos"
    Percentage: "completed / total * 100"
    
Task_Completion_Clears_Todos:
  On_Task_Complete:
    - Mark all remaining todos complete
    - Clear TodoWrite state
    - Archive task to completed/ folder
    - Create final git checkpoint/merge
    
Bidirectional_Sync:
  Todo → Task: "Todo completion updates task progress"
  Task → Todo: "Task status changes affect todo priorities"
  Context: "Both systems share context seamlessly"
```

## Git Integration

```yaml
Branch_Strategy:
  Naming: "task/{id}-{slug}"
  Creation: "Automatic on task start"
  Protection: "Prevent force push, require PR for completion"
  
Commit_Discipline:
  Format: "[{task_id}] {phase}: {description}"
  Atomic: "One logical change per commit"
  Phase_Examples:
    - "[{id}] Analysis: Requirements documented"
    - "[{id}] Impl: {component} implemented"
    - "[{id}] Test: {test_type} tests added"
    - "[{id}] Complete: Task finished"
  
Checkpoints:
  Automatic:
    - Phase transitions
    - Before risky operations
    - Session timeout (>30min)
    - Todo milestone completion
  Manual:
    - /task:pause command
    - /git --checkpoint
    
Cleanup_Workflow:
  On_Complete:
    - Squash merge to main
    - Delete feature branch
    - Archive task to completed/
    - Update project documentation
  Retention:
    - Keep completed tasks 30 days
    - Archive older tasks monthly
    - Prune stale branches weekly
```

## Command Integration

```yaml
Task_Commands:
  create: "/task:create {title} --type {type} --priority {priority}"
  list: "/task:list --status {status}"
  start: "/task:start {id}"
  pause: "/task:pause {id}"
  complete: "/task:complete {id}"
  resume: "/task:resume {id}"
  cancel: "/task:cancel {id}"
  
Auto_Detection_Commands:
  /build → "Analyze complexity → create task if needed → proceed"
  /implement → "Always create task → breakdown → execute"
  /create → "Analyze scope → task if multi-step → proceed"
  
Plan_Mode_Integration:
  exit_plan_mode:
    - Analyze plan complexity automatically
    - Count steps, files, technologies involved
    - If complexity ≥8: Create task with plan content
    - Track plan execution through task system
    
Persona_Activation_Triggers:
  architect: "High complexity system design"
  frontend: "UI/component development requests"
  backend: "API/database implementation work"
  security: "Authentication/authorization features"
```

## User Experience Examples

```yaml
Example_1_Complex_Auto_Creation:
  User_Input: "Build user authentication system"
  System_Analysis: "Score: 11 (build+system+authentication)"
  System_Response: "[Task created: auth-20250623-143052] Starting implementation..."
  Generated_Todos: ["Create user model", "Add registration endpoint", "Implement JWT", "Add tests"]
  User_Experience: "Seamless transition to implementation with task tracking"
  
Example_2_Simple_No_Task:
  User_Input: "Fix login button styling"
  System_Analysis: "Score: 2 (low complexity)"
  System_Response: "No task created"
  Generated_Todos: ["Update button CSS", "Test responsive design"]
  User_Experience: "Direct todo completion without task overhead"
  
Example_3_Session_Recovery:
  Before_Break: "Working on 'Add registration endpoint' (todo 2/8)"
  After_Resume: "Resuming auth system - continuing with registration endpoint"
  State_Restored: "Task context + todo position + git branch + architectural decisions"
  User_Experience: "Seamless continuation as if never interrupted"
  
Example_4_Medium_Complexity:
  User_Input: "Create product catalog component"
  System_Analysis: "Score: 6 (create+component)"
  System_Response: "[Multi-step work detected - creating task] Product catalog implementation"
  Generated_Todos: ["Design component interface", "Implement product list", "Add filtering", "Write tests"]
  User_Experience: "Brief notification, then immediate work start"
```

## Task Structure

```yaml
Task_Structure:
  File_Format:
    Location: ".claudedocs/tasks/{status}/{type}-{id}-{slug}.md"
    Status_Directories: ["pending", "in-progress", "completed", "cancelled"]
    ID_Format: "YYYYMMDD-HHMMSS (timestamp-based unique identifier)"
    
  Task_File_Header:
    Metadata:
      ID: "Unique timestamp identifier"
      Title: "Human-readable task description"
      Type: "feature|bugfix|refactor|docs|test|analysis"
      Status: "pending|in_progress|completed|cancelled"
      Priority: "critical|high|medium|low"
      Created: "ISO 8601 timestamp"
      Updated: "ISO 8601 timestamp"
      Branch: "Git branch name (task/{id}-{slug})"
      
  Content_Structure:
    Overview:
      Description: "Detailed task description and context"
      Objectives: "What needs to be accomplished"
      Success_Criteria: "Definition of done"
      
    Implementation_Plan:
      Phases: "Major development phases"
      Dependencies: "Other tasks or external dependencies"
      Risks: "Potential blockers or challenges"
      
    Progress_Tracking:
      Current_Phase: "Which phase is currently active"
      Completed_Steps: "List of finished work items"
      Next_Steps: "Immediate next actions"
      Blockers: "Current obstacles and workarounds"
      
    Technical_Context:
      Architecture_Decisions: "Key design choices made"
      Files_Modified: "Tracked file changes"
      Git_Commits: "Related commit history"
      Testing_Strategy: "How the work will be verified"
      
  State_Management:
    Status_Transitions:
      pending → in_progress: "Task started, branch created"
      in_progress → completed: "All objectives met, PR merged"
      in_progress → cancelled: "Task abandoned or deprioritized"
      completed → in_progress: "Reopened for additional work"
      
    Automatic_Updates:
      Progress_Calculation: "Based on completed todos vs total"
      Git_Integration: "Commit references and branch status"
      Time_Tracking: "Session time spent on task"
      
  Integration_Points:
    Todo_System:
      Generation: "Create todos from task breakdown"
      Synchronization: "Todo completion updates task progress"
      Context_Sharing: "Shared state between systems"
      
    Git_Integration:
      Branch_Creation: "Automatic feature branch creation"
      Commit_Linking: "Commits reference task ID"
      Merge_Tracking: "PR completion triggers task completion"
      
    Command_System:
      Auto_Creation: "Complex operations trigger task creation"
      Status_Updates: "Commands update task progress"
      Recovery: "Resume interrupted tasks automatically"
```

---
*Task System v4.0.0 - Seamless integration of persistent tasks with dynamic todos for SuperClaude*