Claude-Code-Workflow/.claude/workflows/task-management-principles.md

Task Management Principles

Overview

This document provides complete technical implementation for the task system, including JSON schema, coordination rules, TodoWrite integration, and validation mechanisms.

Unified Task JSON Schema

Core Task Structure

All task files must conform to this schema with support for recursive decomposition:

{
  "id": "impl-1",
  "parent_id": null,
  "title": "Task title describing the work",
  "type": "feature|bugfix|refactor|test|docs",
  "status": "pending|active|completed|blocked|failed",
  "priority": "low|normal|high|critical",
  "agent": "code-developer|planning-agent|test-agent|review-agent",
  "effort": "1h|2h|4h|1d|2d",
  
  "context": {
    "inherited_from": "WFS-user-auth-system",
    "requirements": ["Specific requirement 1", "Specific requirement 2"],
    "scope": ["src/module/*", "tests/module/*"],
    "acceptance": ["Success criteria 1", "Success criteria 2"]
  },
  
  "dependencies": {
    "upstream": ["impl-0"],
    "downstream": ["impl-2", "impl-3"]
  },
  
  "subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"],
  
  "execution": {
    "attempts": 1,
    "current_attempt": {
      "started_at": "2025-09-05T10:35:00Z",
      "checkpoints": ["setup", "implement", "test", "validate"],
      "completed_checkpoints": ["setup", "implement"]
    },
    "history": []
  },
  
  "metadata": {
    "created_at": "2025-09-05T10:30:00Z",
    "started_at": "2025-09-05T10:35:00Z",
    "completed_at": "2025-09-05T13:15:00Z",
    "last_updated": "2025-09-05T13:15:00Z",
    "version": "1.0"
  }
}

Status Enumeration

Standard status values across all systems:

• pending: Task created but not started
• active: Task currently being worked on
• completed: Task successfully finished
• blocked: Task cannot proceed due to dependencies
• failed: Task attempted but failed execution

Type Classification

Standard task types:

• feature: New functionality implementation
• bugfix: Fixing existing issues
• refactor: Code improvement without functionality change
• test: Test implementation or testing tasks
• docs: Documentation creation or updates

Priority Levels

Standard priority values:

• low: Can be deferred
• normal: Standard priority (default)
• high: Should be completed soon
• critical: Must be completed immediately

TodoWrite Integration System

TodoWrite Tool vs TODO_LIST.md File

Clear Distinction: TodoWrite is Claude's internal task tracking tool, TODO_LIST.md is the persistent workflow file

TodoWrite Tool:

• Claude's internal task management interface
• Real-time progress tracking during execution
• Temporary state for active workflow sessions
• Used by agents and commands for immediate task coordination

TODO_LIST.md File:

• Persistent task list stored in workflow session directory
• Cross-referenced with JSON task files
• Maintains task hierarchy and progress visualization
• Provides audit trail and resumable task state

Synchronization Protocol

TodoWrite → TODO_LIST.md:

• TodoWrite task completion triggers TODO_LIST.md checkbox updates
• TodoWrite progress reflected in TODO_LIST.md progress calculations
• TodoWrite task status changes sync to JSON task files

TODO_LIST.md → JSON Task Files:

• Checkbox changes in TODO_LIST.md update JSON task status
• Manual task modifications propagate to JSON files
• Progress calculations derived from JSON task completion

JSON Task Files → TodoWrite:

• Task creation in JSON automatically creates TodoWrite entries when session is active
• JSON status changes reflect in TodoWrite display
• Agent task assignments sync to TodoWrite coordination

Integration Rules

1. Session Active: TodoWrite automatically syncs with TODO_LIST.md
2. Session Paused: TodoWrite state preserved in TODO_LIST.md
3. Session Resumed: TodoWrite reconstructed from TODO_LIST.md and JSON files
4. Cross-Session: TODO_LIST.md provides continuity, TodoWrite provides active session interface

Workflow Integration Schema

Workflow Task Summary

Workflow session contains minimal task references with hierarchical support:

{
  "phases": {
    "IMPLEMENT": {
      "tasks": ["impl-1", "impl-2", "impl-3"],
      "completed_tasks": ["impl-1"],
      "blocked_tasks": [],
      "progress": 33,
      "task_depth": 2,
      "last_sync": "2025-09-05T13:15:00Z"
    }
  }
}

Task Reference Format

Tasks referenced by hierarchical ID, full details in JSON files:

{
  "task_summary": {
    "id": "impl-1",
    "parent_id": null,
    "title": "Task title",
    "status": "completed",
    "type": "feature",
    "depth": 1,
    "progress": 100
  }
}

// Subtask example
{
  "task_summary": {
    "id": "impl-1.2.1",
    "parent_id": "impl-1.2",
    "title": "Detailed subtask",
    "status": "active",
    "type": "implementation",
    "depth": 3,
    "progress": 45
  }
}

Data Ownership Rules

JSON Task Files Own

• Complete task details and context (all levels)
• Execution history and checkpoints
• Parent-child relationships (via parent_id)
• Requirements and acceptance criteria
• Agent assignment and progress tracking
• Hierarchical decomposition state

Workflow Session Owns

• Top-level task ID lists per phase
• Overall progress calculations
• Phase transition triggers
• Global context inheritance rules
• Task depth management (max 3 levels)
• Sync timestamps and validation

Shared Responsibility

• Task status (JSON authoritative, TODO_LIST.md displays)
• Progress calculations (derived from JSON, shown in TODO_LIST.md)
• Hierarchical relationships (JSON defines, TODO_LIST.md visualizes)
• Dependency validation (cross-file consistency)

Synchronization Principles

Automatic Sync Triggers

• Task Creation: Add to workflow task list and TODO_LIST.md
• Status Change: Update TODO_LIST.md checkboxes and progress
• Task Completion: Update TODO_LIST.md and recalculate hierarchy progress
• Task Decomposition: Create child JSON files, update TODO_LIST.md structure
• Context Update: Propagate to child tasks in hierarchy
• Dependency Change: Validate across all hierarchy levels

Sync Direction Rules

1. JSON Task → TODO_LIST.md: Status updates, progress changes, completion
2. JSON Task → Workflow: Task creation, hierarchy changes, phase completion
3. IMPL_PLAN.md → JSON Task: Context updates, requirement changes
4. TODO_LIST.md → JSON Task: Manual status changes via checkboxes
5. Bidirectional: Dependencies, timestamps, hierarchy validation

Conflict Resolution

Priority order for conflicts:

1. Most Recent: Latest timestamp wins
2. Task Authority: Task files authoritative for task details
3. Workflow Authority: Workflow authoritative for phase management
4. Manual Resolution: User confirmation for complex conflicts

Data Integrity Checks

• ID Consistency: All task IDs exist across JSON files and TODO_LIST.md
• Hierarchy Validation: Parent-child relationships are bidirectional and valid
• Depth Limits: No task exceeds 3 levels deep (impl-N.M.P max)
• Status Validation: Status values match enumeration across all files
• Dependency Validation: All dependencies exist and respect hierarchy
• Progress Accuracy: Calculated progress matches hierarchical task completion
• Timestamp Ordering: Created ≤ Started ≤ Completed across hierarchy

Hierarchical Task Decomposition

Decomposition Rules

Maximum Depth: 3 levels (impl-N.M.P)

• Level 1 (impl-N): Main implementation tasks
• Level 2 (impl-N.M): Subtasks with specific focus areas
• Level 3 (impl-N.M.P): Detailed implementation steps

ID Format Standards

impl-1              # Main task
impl-1.1            # Subtask of impl-1
impl-1.1.1          # Detailed subtask of impl-1.1
impl-1.2            # Another subtask of impl-1
impl-2              # Another main task

Parent-Child Relationships

// Parent task (impl-1.json)
{
  "id": "impl-1",
  "parent_id": null,
  "subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"]
}

// Child task (impl-1.1.json)  
{
  "id": "impl-1.1",
  "parent_id": "impl-1",
  "subtasks": ["impl-1.1.1", "impl-1.1.2"]
}

// Grandchild task (impl-1.1.1.json)
{
  "id": "impl-1.1.1", 
  "parent_id": "impl-1.1",
  "subtasks": []  // Leaf node - no further decomposition
}

Progress Calculation

• Leaf tasks: Progress based on execution checkpoints
• Container tasks: Progress = average of all subtask progress
• Workflow progress: Weighted average of all top-level tasks

Status Propagation Rules

• Child → Parent: Parent cannot be "completed" until all children complete
• Parent → Child: Parent "blocked" status may propagate to children
• Sibling Independence: Subtasks at same level operate independently

Context Management

Context Inheritance Chain

Workflow Context
    ↓ (inherits requirements, constraints)
Task Context
    ↓ (distributes scope, specific requirements)
Subtask Context

Context Distribution Rules

• Requirements: Flow from workflow to tasks
• Scope: Refined at each level (workflow → task → subtask)
• Constraints: Apply globally from workflow
• Acceptance Criteria: Specific to each task level

Dynamic Context Updates

• Changes in workflow context propagate to tasks
• Task-specific context remains isolated
• Subtask context inherits from parent task
• Context versioning tracks changes

Agent Integration

Agent Assignment Logic

Based on task type and complexity:

• Planning tasks → planning-agent
• Implementation → code-developer
• Testing → test-agent
• Documentation → docs-agent
• Review → review-agent

Execution Context Preparation

{
  "execution_context": {
    "task": {
      "id": "IMPL-001",
      "requirements": ["from task context"],
      "scope": ["from task context"]
    },
    "workflow": {
      "session": "WFS-2025-001",
      "phase": "IMPLEMENT",
      "global_context": ["from workflow"]
    },
    "agent": {
      "type": "code-developer",
      "capabilities": ["coding", "testing"],
      "context_optimizations": ["code_patterns"]
    }
  }
}

Error Handling

Common Error Scenarios

1. JSON Task File Missing: Recreate from TODO_LIST.md or parent task data
2. Status Mismatch: JSON files are authoritative, update TODO_LIST.md
3. Hierarchy Broken: Reconstruct parent-child relationships from IDs
4. Invalid Dependencies: Validate across all hierarchy levels
5. Schema Version Mismatch: Migrate to current hierarchical schema
6. Orphaned Tasks: Clean up or reassign to proper parent/workflow
7. Depth Violation: Flatten excessive hierarchy to 3 levels max

Recovery Strategies

• Automatic Recovery: For common, well-defined conflicts
• Validation Warnings: For non-critical inconsistencies
• Manual Intervention: For complex or ambiguous conflicts
• Graceful Degradation: Continue with best available data

Validation Rules

• All task IDs must be unique and follow impl-N[.M[.P]] format
• Hierarchical IDs must have valid parent relationships
• Maximum depth of 3 levels (impl-N.M.P)
• Status values must be from defined enumeration
• Dependencies must reference existing tasks at appropriate levels
• Parent tasks cannot be completed until all subtasks complete
• Timestamps must be chronologically ordered
• Required fields cannot be null or empty

Implementation Guidelines

File Organization

.task/
├── impl-1.json            # Main task
├── impl-1.1.json          # Level 2 subtask
├── impl-1.1.1.json        # Level 3 detailed subtask
├── impl-1.2.json          # Level 2 subtask
└── impl-2.json            # Another main task

.workflow/WFS-[topic-slug]/
├── workflow-session.json   # Master session
├── IMPL_PLAN.md           # Planning document
└── TODO_LIST.md           # Progress tracking and task registry

Performance Considerations

• Lazy Loading: Load task details only when needed
• Batch Operations: Group sync operations for efficiency
• Incremental Updates: Only sync changed data
• Cache Management: Cache frequently accessed task data

Testing Requirements

• Schema validation for all task operations
• Sync consistency across workflow/task boundaries
• Error recovery scenario testing
• Performance testing with multiple tasks
• Concurrent access handling

Success Metrics

• Zero data loss during sync operations
• Consistent task status across systems
• Fast task operations (< 100ms for single task)
• Reliable error recovery
• Complete audit trail of changes