Claude-Code-Workflow/.claude/commands/task/sync.md

name, description, usage, argument-hint, examples

name	description	usage	argument-hint	examples
task-sync	Synchronize task data with workflow session	/task:sync [--force] [--dry-run]	optional force sync or dry run	/task:sync /task:sync --force /task:sync --dry-run

Task Sync Command (/task:sync)

Overview

Ensures bidirectional synchronization between hierarchical JSON tasks, TODO_LIST.md, and workflow-session.json.

Core Principles

System Architecture: @~/.claude/workflows/unified-workflow-system-principles.md

Bidirectional Sync Operations

1. JSON Task Files → TODO_LIST.md Sync

Authoritative Source: JSON task files in .task/ directory

• Status Updates: pending → active → completed reflected in checkboxes
• Hierarchical Progress: Parent progress = average of children (up to 3 levels)
• Structure Sync: TODO_LIST.md hierarchy matches JSON parent_id relationships
• Cross-References: Links to JSON files and summary files validated
• Progress Rollup: Automatic calculation from leaf tasks to root

2. JSON Task Files → Workflow Session Sync

Session State Updates: workflow-session.json reflects current task state

• Task Lists: Main task IDs updated per phase
• Progress Metrics: Overall and phase-specific completion percentages
• Complexity Assessment: Structure level based on current task count
• Blocked Task Detection: Dependency analysis across entire hierarchy
• Session Metadata: Last sync timestamps and validation status

3. Workflow Session → JSON Task Sync

Context Propagation: Session context distributed to individual tasks

• Global Context: Workflow requirements inherited by all tasks
• Requirement Updates: Changes in session context propagated
• Issue Associations: Workflow-level issues linked to relevant tasks
• Phase Transitions: Task context updated when phases change

4. TodoWrite Tool → File System Sync

Real-time Coordination: TodoWrite tool state synced with persistent files

• Active Task Sync: TodoWrite status reflected in JSON files
• Completion Triggers: TodoWrite completion updates JSON and TODO_LIST.md
• Progress Coordination: TodoWrite progress synced with file-based tracking
• Session Continuity: TodoWrite state preserved in TODO_LIST.md

Sync Rules

Automatic Sync Points

• After /task:create - Add to workflow
• After /task:execute - Update progress
• After /task:replan - Sync changes
• After /workflow:* commands - Propagate context

Conflict Resolution

Priority order:

1. Recently modified (timestamp)
2. More complete data
3. User confirmation (if needed)

Usage Examples

Standard Sync with Report Generation

/task:sync

🔄 Comprehensive Task Synchronization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Analyzing file system state...
- JSON task files: 8 tasks across 3 levels in .task/
- TODO_LIST.md: Present, 8 displayed tasks, last modified 2h ago
- workflow-session.json: 3 main tasks tracked, Level 1 structure
- Summary files: 3 completed task summaries in .summaries/

Validating cross-references...
✅ Parent-child relationships: All valid
✅ Hierarchy depth: Within limits (max 3 levels)
✅ File naming: Follows impl-N.M.P format

Found synchronization differences:
- Task impl-1.2: completed in JSON, pending in TODO_LIST.md checkbox
- Progress: impl-1 shows 75% (from subtasks) vs 45% in session
- Hierarchy: impl-2.3.1 exists in JSON but missing from TODO_LIST.md
- Cross-refs: Summary link for impl-1.2 missing in TODO_LIST.md

Synchronizing files...
✅ Updated impl-1.2 checkbox: [ ] → [x] in TODO_LIST.md
✅ Recalculated hierarchical progress: impl-1 = 75%
✅ Added impl-2.3.1 to TODO_LIST.md hierarchy display
✅ Updated summary link: impl-1.2 → .summaries/IMPL-1.2-summary.md
✅ Propagated context updates to 3 task files
✅ Updated workflow-session.json progress metrics

Generating sync report...
✅ Sync report saved: .summaries/sync-report-20250907-160000.md

Sync complete: 6 updates applied, 0 conflicts resolved
Next sync recommended: In 1 hour or after next task operation

Dry Run with Detailed Analysis

/task:sync --dry-run

🔍 Sync Analysis (Dry Run Mode)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scanning .task/ directory: 8 JSON files found
Analyzing TODO_LIST.md: Last modified 2h ago
Checking workflow-session.json: In sync
Validating .summaries/: 3 summary files present

Potential changes identified:
ℹ️ Update 2 task statuses: impl-1.2, impl-1.3
ℹ️ Recalculate progress for parent: impl-1 (67% → 75%)
ℹ️ Add 1 missing cross-reference in TODO_LIST.md
ℹ️ Update workflow session progress: 45% → 62%
ℹ️ Generate missing summary link for impl-1.2

File changes would be made to:
- TODO_LIST.md (3 line changes)
- workflow-session.json (progress update)
- No JSON task files need changes (already authoritative)

Conflicts detected: None
Risk level: Low
Estimated sync time: <5 seconds

(No actual changes made - run without --dry-run to apply)

Force Sync with Backup

/task:sync --force

⚠️ Force Sync Mode - Creating Backups
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Backing up current state...
✅ TODO_LIST.md → .summaries/backup-TODO_LIST-20250907-160000.md
✅ workflow-session.json → .summaries/backup-session-20250907-160000.json

Force sync operations:
❗ Using JSON task files as authoritative source
❗ Overwriting TODO_LIST.md without conflict resolution
❗ Rebuilding workflow-session.json task data
❗ Regenerating all cross-references
❗ Recalculating all progress from scratch

Sync completed with authority conflicts resolved:
✅ 3 conflicts overwritten in favor of JSON files
✅ TODO_LIST.md completely regenerated
✅ workflow-session.json task list rebuilt
✅ All cross-references validated and updated

Backup files available for rollback if needed:
- .summaries/backup-TODO_LIST-20250907-160000.md
- .summaries/backup-session-20250907-160000.json

Force sync report: .summaries/force-sync-20250907-160000.md

Data Integrity Checks

Validation Steps

1. File Existence: Both JSON files exist
2. Session Match: Same session_id
3. ID Consistency: All task IDs valid
4. Status Logic: No impossible states
5. Progress Math: Calculation accurate

Error Recovery

❌ Sync failed: tasks.json corrupted
→ Attempting recovery from backup...
✅ Restored from backup
→ Retry sync? (y/n)

Progress Calculation

progress = (completed_tasks / total_tasks) * 100

// With subtasks
weighted_progress = sum(task.weight * task.progress) / total_weight

JSON Updates

workflow-session.json

{
  "phases": {
    "IMPLEMENT": {
      "tasks": ["IMPL-001", "IMPL-002", "IMPL-003"],
      "completed_tasks": ["IMPL-001", "IMPL-002"],
      "progress": 67,
      "last_sync": "2025-01-16T14:00:00Z"
    }
  }
}

Individual Task Files

Each task file maintains sync metadata:

{
  "id": "IMPL-001",
  "title": "Build authentication module", 
  "status": "completed",
  "type": "feature",
  "agent": "code-developer",
  
  "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",
    "last_sync": "2025-09-05T13:15:00Z",
    "version": "1.0"
  }
}

Performance & File Management

Sync Performance

• Incremental Analysis: Only processes changed files since last sync
• Cached Validation: Reuses validation results for unchanged files
• Batch File Updates: Groups related changes for efficiency
• Typical Sync Time: <100ms for standard workflows, <500ms for complex

Generated Reports

Automatic Documentation: Every sync creates audit trail

• Standard Sync Report: .summaries/sync-report-[timestamp].md
• Dry Run Analysis: .summaries/sync-analysis-[timestamp].md
• Force Sync Report: .summaries/force-sync-[timestamp].md
• Conflict Resolution Log: Embedded in sync reports
• Backup Files: Created during force operations

File System Maintenance

• Cleanup Policy: Keep last 10 sync reports, archive older ones
• Backup Management: Automatic cleanup of force sync backups after 7 days
• Error Recovery: Complete rollback capability from backup files
• Integrity Monitoring: Continuous validation of file system consistency

File System Integration

Integration Points

• JSON Task Files: Authoritative source for all task data
• TODO_LIST.md: Display layer synchronized from JSON files
• workflow-session.json: High-level session state and progress
• Summary Files: Completion documentation linked from TODO_LIST.md
• TodoWrite Tool: Real-time task management interface

File Output Summary

Generated Files:

• Sync Reports: .summaries/sync-report-[timestamp].md
• Backup Files: .summaries/backup-[file]-[timestamp].[ext]
• Analysis Reports: .summaries/sync-analysis-[timestamp].md
• Updated TODO_LIST.md: Refreshed with current task state
• Updated workflow-session.json: Current progress and task references

Quality Assurance

• Pre-sync Validation: File existence and format checks
• Post-sync Verification: Cross-reference validation
• Rollback Testing: Backup restoration validation
• Performance Monitoring: Sync time and efficiency tracking

Related Commands

• /task:context --sync-check - Validate current sync status
• /task:create - Creates tasks requiring sync
• /task:execute - Generates summaries requiring sync
• /task:replan - Structural changes requiring sync
• /workflow:sync - Full workflow document synchronization