Easy Sync

Synchronize task orchestration status with git commits, ensuring bidirectional consistency between version control activity and task tracking state.

When to Use This Command

Run this command when...

• Task tracking state has drifted from actual git commit history and needs reconciliation
• You have been working outside Claude and want to update task status based on recent commits
• A team member pushed commits that correspond to tracked tasks but the status was not updated
• You want to verify that all completed commits have matching task completions and vice versa
• Sprint boundaries require a full synchronization between code delivery and tracking records

Quick Start

Copy
# .claude/commands/easy-sync.md
---
name: Easy Sync
description: Sync task status with git commit history bidirectionally
command: true
---
Synchronize: $ARGUMENTS

1. Scan git history for task-related commits
2. Compare against current task tracking state
3. Identify discrepancies between git and task status
4. Apply updates to bring both systems into alignment

Copy
# Invoke the command
claude "/easy-sync"

# Expected output
# > Scanning git history (last 50 commits)...
# > Comparing against task state...
# > Discrepancies found:
# >   TASK-005: Marked pending, but commit abc1234 implements it (2 days ago)
# >   TASK-009: Marked complete, but no matching commits found
# >   TASK-012: 3 commits found, task still marked in-progress
# > Applying updates:
# >   TASK-005: pending -> completed (matched commit abc1234)
# >   TASK-009: flagged for review (no commit evidence)
# >   TASK-012: kept in-progress (partial implementation detected)
# > Sync complete: 1 updated, 1 flagged, 1 unchanged

Core Concepts

Concept	Description
Bidirectional Sync	Updates both task state from git evidence and flags git gaps from task state
Commit Parsing	Extracts task IDs from commit messages using configurable patterns
Evidence Matching	Correlates commits to tasks based on message content, branch names, and file paths
Conflict Resolution	When git and task state disagree, surfaces the conflict with evidence for manual resolution
Check Mode	Reports discrepancies without making changes for safe preview

Easy Sync Reconciliation
=========================

  Git History                Task State
  +-----------+             +-----------+
  | commit A  |             | TASK-001  |
  | commit B  |    diff     | TASK-002  |
  | commit C  | <-------->  | TASK-003  |
  | commit D  |             | TASK-004  |
  +-----------+             +-----------+
        |                        |
        +----------+-------------+
                   |
            [Reconcile Engine]
                   |
         +---------+---------+
         |         |         |
      Updated   Flagged   Unchanged
      tasks     conflicts tasks

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Sync scope or specific task IDs	all tasks	"TASK-005 TASK-009"	No
commit_range	Git commit range to scan	last 50 commits	"HEAD~20..HEAD"	No
task_pattern	Regex to extract task IDs from commit messages	"TASK-\\d+"	"FE-\\d+"	No
auto_apply	Apply updates without confirmation prompts	false	true	No
check_only	Report discrepancies without making changes	false	true	No

Best Practices

1. Use consistent task ID formats in commits -- Prefix every commit message with the task ID (e.g., "TASK-005: implement login form") so the sync engine can match commits to tasks automatically.

2. Run sync at session boundaries -- Sync at the start and end of each work session to maintain alignment, especially when multiple developers contribute to the same task set.

3. Preview with check_only first -- Use check_only: true before applying changes to review what the sync engine plans to update and catch any mismatches in its logic.

4. Configure task_pattern for your project -- If your project uses Jira (FE-123), Linear (LIN-456), or GitHub Issues (#78), set the appropriate regex pattern for accurate commit parsing.

5. Handle flagged conflicts promptly -- Tasks flagged as conflicts (marked complete without commit evidence) may indicate work done in a different branch or manual status changes. Investigate rather than ignoring.

Common Issues

Commits without task IDs are invisible: The sync engine relies on task ID patterns in commit messages. Commits without IDs are not matched to any task. Adopt a commit convention that always includes the task reference.

Branch-based work not reflected: If work is in a feature branch that has not been merged, commits may not appear in the scan range. Extend the commit range or specify the branch: "sync --branch feature/auth."

Multiple tasks in one commit cause ambiguity: A commit referencing "TASK-005, TASK-006" may be attributed to both tasks. The sync engine handles this, but verify the split is accurate for partially completed work.