---
name: task-sync
description: >
  Synchronize task lifecycle with git commits and Claude's TodoWrite tool.
  PROACTIVELY use when: (1) user says "sync tasks", "task done", "closing task",
  (2) committing code that references a task file, (3) starting work on a formal task
  from .tasks/active/, (4) user mentions moving a task to completed.
  Manages the auto-completed staging workflow and keeps TodoWrite in sync.
allowed-tools: Read, Edit, Write, Bash, Glob, Grep, TodoWrite
---

# Task Sync

Synchronize `.tasks/` lifecycle with git operations and Claude's TodoWrite tool.

## Full Sync Workflow

When user says "sync tasks" or similar, perform ALL of the following checks:

### 1. Check for Duplicate Task Numbers

```bash
ls .tasks/active/*.md .tasks/completed/*.md .tasks/auto-completed/*.md 2>/dev/null | \
  xargs -I {} basename {} | sed 's/-.*//' | sort | uniq -d
```

If duplicates found:
- Identify the highest task number
- Renumber the newer/less-progressed duplicate to next available number
- Stage the rename

### 2. Find Stale "In Progress" Tasks

```bash
grep -l "In Progress" .tasks/active/*.md 2>/dev/null
```

For each "In Progress" task:
- Check if implementation is actually complete (grep for checked boxes `[x]`)
- Check if code exists in codebase (grep for related files/functions)
- If complete: update status to "Done", move to `auto-completed/`
- If stale (>30 days no update): flag for user review

### 3. Check Recently Modified Tasks

```bash
fd --changed-within 7d -e md . .tasks/active/
```

Sync these to TodoWrite as priority items.

### 4. Check Auto-Completed Queue

```bash
ls .tasks/auto-completed/*.md 2>/dev/null | wc -l
```

If tasks pending review, remind user.

### 5. Sync TodoWrite

Update TodoWrite with:
- Recently completed items (mark as completed)
- Current priority tasks from implementation schedule
- Any "In Progress" tasks

### 6. Auto-Commit (NOT Push)

Stage and commit all task changes:

```bash
git add .tasks/
git commit -m "$(cat <<'EOF'
chore(tasks): sync task states

- [list changes made]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
```

**NEVER auto-push.** User must push manually.

## Directory Structure

```
.tasks/
├── active/           # Tasks currently being worked on
├── auto-completed/   # Staging area for review before final completion
├── completed/        # Reviewed and confirmed complete
├── README.md
└── TEMPLATE.md
```

## Task Lifecycle

### Starting a Task

When user begins work on a formal task:

1. Read the task file from `.tasks/active/NNNN-name.md`
2. Update status from "Draft" to "In Progress"
3. Add Progress Log entry: `- YYYY-MM-DD: Started implementation`
4. Sync TodoWrite with the task's Implementation Plan checkboxes
5. Auto-commit the status change

### Completing a Task

When user indicates task completion:

1. Update task file:
   - Set `**Status**: Done`
   - Set `**Completed**: YYYY-MM-DD`
   - Add Progress Log entry: `- YYYY-MM-DD: Completed`

2. Move file to staging:
   ```bash
   mv .tasks/active/NNNN-name.md .tasks/auto-completed/
   ```

3. Update TodoWrite to mark related items complete

4. Auto-commit:
   ```bash
   git add .tasks/
   git commit -m "chore(tasks): complete NNNN-name"
   ```

### Reviewing Auto-Completed Tasks

Periodically remind user to review `auto-completed/`:

```bash
ls .tasks/auto-completed/*.md 2>/dev/null | wc -l
```

If tasks are pending review, suggest:
- Review each task for completeness
- Move to `completed/` when satisfied:
  ```bash
  mv .tasks/auto-completed/NNNN-name.md .tasks/completed/
  ```

## Detecting Completed Tasks

A task is likely complete if:

1. **All implementation checkboxes are checked:**
   ```bash
   grep -c "\- \[x\]" taskfile.md  # checked
   grep -c "\- \[ \]" taskfile.md  # unchecked
   ```

2. **Related code exists in codebase:**
   - Search for files/patterns mentioned in task
   - Check if described feature is implemented

3. **Task hasn't been updated in >30 days** but status is "In Progress"

## Git Integration

### Auto-Commit Rules

- **DO auto-commit:** Task status changes, renames, moves
- **DO NOT auto-push:** User must explicitly push
- **Commit message format:** `chore(tasks): <action> NNNN-name`

### Commit Patterns

| Action | Commit Message |
|--------|---------------|
| Start task | `chore(tasks): start NNNN-name` |
| Complete task | `chore(tasks): complete NNNN-name` |
| Sync tasks | `chore(tasks): sync task states` |
| Fix duplicates | `chore(tasks): fix duplicate task numbers` |

## TodoWrite Synchronization

Map task Implementation Plan to TodoWrite:

```markdown
## Implementation Plan (in task file)
- [ ] Step 1
- [x] Step 2
- [ ] Step 3
```

Becomes TodoWrite entries:
- "Step 1" - pending
- "Step 2" - completed
- "Step 3" - pending

## Finding Tasks

```bash
# List active tasks
ls .tasks/active/*.md

# Find next task number
ls .tasks/active/*.md .tasks/completed/*.md .tasks/auto-completed/*.md 2>/dev/null | \
  xargs -I {} basename {} | sed 's/-.*//' | sort -n | tail -1

# Tasks pending review
ls .tasks/auto-completed/*.md

# Find duplicates
ls .tasks/active/*.md .tasks/completed/*.md .tasks/auto-completed/*.md 2>/dev/null | \
  xargs -I {} basename {} | sed 's/-.*//' | sort | uniq -d
```

## Task File Format

See `references/task-format.md` for the complete task template structure.