task-status-sync — how to use task-status-sync how to use task-status-sync, task-status-sync alternative, task-status-sync setup guide, what is task-status-sync, task-status-sync vs manual tracking, task-status-sync install for AI agents, Spec-Driven Development with task-status-sync, task-status-sync for atomic synchronization, task-status-sync and Claude Code workflows

<quick_start> <enforcement_model> Intercept and convert manual edits to task-tracker commands:

1. Detect attempt: Monitor for Edit/Write tool usage on NOTES.md or tasks.md
2. Extract intent: Parse what change the user/Claude wants to make
3. Convert to command: Generate equivalent task-tracker command
4. Execute atomically: Run task-tracker to update both files simultaneously
5. Provide feedback: Explain the conversion and show the result

Example workflow:

User: "Mark T001 as completed"

❌ BLOCKED: Direct edit to tasks.md
✅ AUTO-CONVERTED: .spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes -TaskId T001

Result:
- tasks.md: - [X] T001 Create database schema
- NOTES.md: ✅ T001: Create database schema - est (2025-11-19 10:30)

</enforcement_model>

<allowed_operations> ✅ Permitted (read-only):

• Read NOTES.md to understand progress
• Read tasks.md to see task list
• Read error-log.md to diagnose failures

✅ Permitted (through task-tracker):

• Mark tasks complete: mark-done-with-notes
• Mark tasks in progress: mark-in-progress
• Mark tasks failed: mark-failed
• Sync status: sync-status
• Get next task: next
• Get summary: summary
• Validate: validate

❌ Blocked (auto-converted):

• Direct Edit/Write to tasks.md
• Direct Edit/Write to NOTES.md
• Manual checkbox changes ([ ] → [X])
• Manual completion markers (✅ T001) </allowed_operations>

<task_tracker_commands> Available task-tracker.sh / task-tracker.ps1 actions:

bash
1# Get current status
2.spec-flow/scripts/bash/task-tracker.sh status -Json
3
4# Mark task completed with full details
5.spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes \
6  -TaskId T001 \
7  -Notes "Created Message model with validation" \
8  -Evidence "pytest: 25/25 passing" \
9  -Coverage "92% (+8%)" \
10  -CommitHash "abc123" \
11  -Duration "15min"
12
13# Mark task in progress
14.spec-flow/scripts/bash/task-tracker.sh mark-in-progress -TaskId T002
15
16# Mark task failed
17.spec-flow/scripts/bash/task-tracker.sh mark-failed \
18  -TaskId T003 \
19  -ErrorMessage "Tests failing: ImportError on MessageService"
20
21# Sync tasks.md to NOTES.md (migration utility)
22.spec-flow/scripts/bash/task-tracker.sh sync-status
23
24# Get next available task
25.spec-flow/scripts/bash/task-tracker.sh next -Json
26
27# Get phase-wise summary
28.spec-flow/scripts/bash/task-tracker.sh summary -Json
29
30# Validate task file structure
31.spec-flow/scripts/bash/task-tracker.sh validate -Json

See references/task-tracker-api.md for complete API reference. </task_tracker_commands> </quick_start>

Watch for these patterns that indicate task status updates:

Direct file edits:

• Edit(file_path: "*/tasks.md", ...)
• Edit(file_path: "*/NOTES.md", ...)
• Write(file_path: "*/tasks.md", ...)
• Write(file_path: "*/NOTES.md", ...)

Verbal indicators:

• "Mark T001 as complete"
• "Update task status for T002"
• "Task T003 is done"
• "Completed T004"
• "T005 failed"

Checkbox change patterns:

• old_string: "- [ ] T001" → new_string: "- [X] T001"
• Adding ✅ markers to NOTES.md manually </detection_phase>

<interception_phase> 2. Intercept and Block Manual Edits

When Edit/Write detected on tasks.md or NOTES.md:

⛔ MANUAL EDIT BLOCKED

File: specs/001-feature/tasks.md
Attempted change: Mark T001 as [X] completed

❌ Reason: Manual edits break atomic sync between tasks.md and NOTES.md

✅ Solution: Use task-tracker command instead

Auto-converting to:
  .spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes -TaskId T001

This atomically updates:
  - tasks.md checkbox: - [X] T001
  - NOTES.md marker: ✅ T001: ... - est (2025-11-19 10:30)
  - Progress summary in tasks.md (if update-tasks-summary.ps1 exists)

Do NOT execute the manual edit. Instead, proceed to conversion phase. </interception_phase>

<conversion_phase> 3. Convert Manual Edit to Task-Tracker Command

Parse the intended change:

Extract from Edit/Write tool parameters:

• TaskId: T### from checkbox pattern or ✅ marker
• NewStatus: Infer from checkbox ([X] = completed, [~] = in-progress, [ ] = pending)
• Notes: Extract from NOTES.md addition or Edit context
• ErrorMessage: Extract if marking failed

Generate equivalent command:

javascript
1// Pseudo-logic
2if (newStatus === 'X' || intent === 'mark complete') {
3  command = 'mark-done-with-notes'
4  params = {
5    TaskId: extractedTaskId,
6    Notes: extractedNotes || "",
7    Duration: "est"  // Default if not specified
8  }
9}
10else if (newStatus === '~' || intent === 'mark in progress') {
11  command = 'mark-in-progress'
12  params = { TaskId: extractedTaskId }
13}
14else if (intent === 'mark failed' || errorMessage present) {
15  command = 'mark-failed'
16  params = {
17    TaskId: extractedTaskId,
18    ErrorMessage: extractedErrorMessage
19  }
20}

Validation before execution:

Check that:

• TaskId exists in tasks.md
• Status transition is valid (pending → in-progress → completed)
• Required fields present (e.g., ErrorMessage for mark-failed)

If validation fails, auto-fix where possible:

• Missing TaskId → Extract from context or ask user
• Invalid transition → Warn and suggest correct flow
• Missing ErrorMessage → Prompt for details

See references/conversion-logic.md for detailed conversion rules. </conversion_phase>

<execution_phase> 4. Execute Task-Tracker Command

bash
1# Platform detection
2if (platform === 'win32') {
3  script = '.spec-flow/scripts/bash/task-tracker.sh'  # Uses WSL or delegates to PS
4} else if (platform === 'linux' || platform === 'darwin') {
5  script = '.spec-flow/scripts/bash/task-tracker.sh'
6}
7
8# Execute with Bash tool
9Bash(`${script} ${command} -TaskId ${TaskId} [additional params] -Json`)

Parse JSON output:

json
1{
2  "Success": true,
3  "TaskId": "T001",
4  "Message": "Task T001 marked complete in both tasks.md and NOTES.md",
5  "TasksFile": "specs/001-feature/tasks.md",
6  "NotesFile": "specs/001-feature/NOTES.md",
7  "PhaseMarker": "[RED]"
8}

Provide feedback:

✅ TASK STATUS UPDATED ATOMICALLY

Task T001 marked complete:
  - tasks.md: Updated checkbox to [X]
  - NOTES.md: Added completion marker
  - Phase: [RED] (TDD red phase)

Files synchronized:
  - specs/001-feature/tasks.md
  - specs/001-feature/NOTES.md

Next steps:
  - Run: task-tracker.sh next
  - Continue with T002

</execution_phase>

<validation_phase> 5. Validate Task-Tracker Usage

Common mistakes to auto-fix:

TDD validation:

Check if test task completed before implementation:

• If marking T002 (implement) complete but T001 (test) is pending → warn
• Recommendation: "Complete T001 (test) before T002 (implement) for TDD"

Parallel safety:

• If more than 2 tasks in-progress → warn: "Exceeds parallel limit (2)"
• If file path conflicts detected → block: "T002 and T003 both modify app.py"

See references/validation-rules.md for complete validation logic. </validation_phase> </workflow>

<anti_patterns> Avoid these mistakes that break sync:

1. Manual checkbox edits

markdown
1❌ BAD (manual edit to tasks.md):
2- [X] T001 Create database schema
3
4✅ GOOD (task-tracker command):
5task-tracker.sh mark-done-with-notes -TaskId T001 -Notes "Created schema"

2. Adding NOTES.md markers manually

markdown
1❌ BAD (manual edit to NOTES.md):
2✅ T001: Created database schema
3
4✅ GOOD (task-tracker handles NOTES.md):
5task-tracker.sh mark-done-with-notes -TaskId T001
6# Atomically updates both files

3. Inconsistent states

markdown
1❌ BAD (tasks.md says pending, NOTES.md says complete):
2tasks.md: - [ ] T001 Create schema
3NOTES.md: ✅ T001: Created schema
4
5✅ GOOD (atomic update ensures consistency):
6Both files updated simultaneously via task-tracker

4. Skipping in-progress marker

markdown
1❌ BAD (pending → completed without in-progress):
2Can lose tracking of what's actively being worked on
3
4✅ GOOD (mark in-progress first):
51. task-tracker.sh mark-in-progress -TaskId T001
62. [implement task]
73. task-tracker.sh mark-done-with-notes -TaskId T001

5. Missing task completion evidence

markdown
1❌ BAD (no evidence of completion):
2✅ T001 - est (timestamp)
3
4✅ GOOD (include evidence, coverage, commit):
5✅ T001: Created Message model - 15min (2025-11-19 10:30)
6  - Evidence: pytest: 25/25 passing
7  - Coverage: 92% (+8%)
8  - Committed: abc123

</anti_patterns>

<success_criteria> Task status sync is working correctly when:

• ✓ All task completions use task-tracker commands
• ✓ tasks.md checkboxes and NOTES.md markers are always synchronized
• ✓ No manual edits to tasks.md or NOTES.md occur
• ✓ Attempted manual edits are auto-converted to task-tracker commands
• ✓ Task-tracker validation catches and fixes common mistakes
• ✓ TDD flow is enforced (tests before implementation)
• ✓ Parallel task limit (2) is respected
• ✓ File path conflicts are detected and prevented
• ✓ Error log entries are created for failed tasks
• ✓ Progress summary stays updated with velocity metrics

Detection working when:

• Edit/Write attempts to tasks.md are intercepted
• Verbal task completion mentions are recognized
• Checkbox change patterns are detected
• Auto-conversion generates correct task-tracker commands

Validation working when:

• Invalid task IDs are caught and corrected
• Invalid status transitions are prevented or guided
• TDD violations are warned
• Parallel safety limits are enforced </success_criteria>

<reference_guides> For detailed implementation and troubleshooting:

• references/task-tracker-api.md - Complete task-tracker command reference with examples
• references/conversion-logic.md - Manual edit → task-tracker command conversion rules
• references/validation-rules.md - Task status validation and auto-fix logic
• references/file-formats.md - tasks.md and NOTES.md structure and patterns </reference_guides>