todowrite-integration

TodoWrite Integration Reference

> **Scope**: TodoWrite patterns for multi-agent coordination — task structure, dependencies, and completion verification. > **Version range**: Claude Code TodoWrite system (all versions) > **Generated**: 2026-04-09

---

Overview

TodoWrite tracks agent task ownership, dependencies, and completion. Keep TodoWrite synchronized with STATUS.md and PROGRESS.md — a task marked `completed` in TodoWrite but not in STATUS.md creates phantom progress.

---

Pattern Table

| State | TodoWrite Status | STATUS.md Entry | Trigger | |-------|-----------------|-----------------|---------| | Task not started | `pending` | Not listed | Initial setup | | Agent assigned | `in_progress` | Active with attempt count | On dispatch | | Agent completed | `completed` | Phase marked done | On verified success | | Agent blocked | `in_progress` | Blocked section | After 3/3 FAILED + BLOCKERS.md | | Task cancelled | Remove from list | Update phase status | After root cause changes strategy |

---

Correct Patterns

Agent Assignment with Dependencies

Structure each task with explicit `blockedBy` when it depends on prior output.

Task: "Phase 1: Generate database schema"
  id: phase-1-schema
  status: in_progress
  assigned: database-engineer
  output: schema.sql

Task: "Phase 2: ORM models"
  id: phase-2-models
  status: pending
  blockedBy: phase-1-schema
  assigned: python-general-engineer
  output: src/models/*.py

Task: "Phase 3: API endpoints"
  id: phase-3-api
  status: pending
  blockedBy: phase-2-models
  assigned: nodejs-api-engineer
  output: src/routes/*.js

Task: "Phase 4: Integration tests"
  id: phase-4-tests
  status: pending
  blockedBy: phase-3-api
  assigned: nodejs-api-engineer, python-general-engineer (parallel)
  output: tests/integration/*

---

Completion Verification Before Status Update

Never mark `completed` based on agent claim alone — verify with success criteria first.

Verification sequence:
1. Agent reports: "Phase 1 complete, schema.sql created"
2. VERIFY: ls -la schema.sql  (file must exist)
3. VERIFY: python3 -c "import json; open('schema.sql')"
4. VERIFY: SUCCESS CRITERIA from HANDOFF.md all pass
5. ONLY THEN: Update TodoWrite to completed
6. THEN: Update STATUS.md
7. THEN: Update PROGRESS.md if context >70%

---

Parallel Task Structure

For parallel tasks, assign non-overlapping file domains.

Task: "Phase 4: Integration tests (parallel)"
  id: phase-4-tests
  status: in_progress
  blockedBy: phase-3-api
  parallel_agents:
    - agent: nodejs-api-engineer
      files: tests/integration/api/*.test.js
      id: phase-4a-api-tests
    - agent: python-general-engineer
      files: tests/integration/models/*.test.py
      id: phase-4b-model-tests

File domains MUST NOT overlap. If they do, serialize instead.

---

Pattern Catalog

<!-- no-pair-required: section header, not an individual failure mode -->

Verify Before Marking Complete

**Detection**:

grep -B5 "completed" todo*.md 2>/dev/null | grep -v "VERIFY\|exits 0\|tests pass"

**Preferred action**: Run success criteria from HANDOFF.md before updating status. Every `completed` transition must include verification evidence:

Task: "Implement user endpoint"
  status: completed
  verified: npm test src/routes/users.test.js → exit 0, 12 tests passed

---

Declare blockedBy on Every Dependent Task

**Detection**:

grep -B2 "Phase [2-9]\|depends on\|requires" todo*.md 2>/dev/null | grep -v "blockedBy"

**Preferred action**: Add `blockedBy: {prior-task-id}` to every task that reads output from a prior task.

---

Split Multi-Agent Work into Per-Agent Tasks

**Detection**:

grep -A5 "assigned:" todo*.md 2>/dev/null | grep -E "assigned:.*,.*,"

**Preferred action**: Split into `parallel_agents` subtasks with own file domain, id, and success criteria. Each agent's retry count tracks independently.

---

Error-Fix Mappings

| Symptom | Root Cause | Fix | |---------|------------|-----| | Phase N+1 dispatched before Phase N output | Missing `blockedBy` | Add `blockedBy: phase-N-id` | | Task `completed` but next agent reports missing files | Premature completion | Require verification before `completed` | | Two agents edit conflicting files | Multi-agent single task | Split into parallel_agents with non-overlapping domains | | Can't determine which tasks are ready | No dependency chain | Rebuild TodoWrite with explicit `blockedBy` | | Fresh agent re-does completed tasks | TodoWrite not synced with PROGRESS.md | Update PROGRESS.md with TodoWrite completed list |

---

Detection Commands Reference

# Find tasks without blockedBy that reference prior phases
grep -B2 "Phase [2-9]\|depends on\|requires" todo*.md 2>/dev/null | grep -v "blockedBy"

# Find completed tasks without verification evidence
grep -B5 "completed" todo*.md 2>/dev/null | grep -v "VERIFY\|exits 0\|tests pass\|verified:"

# Check for multi-agent single-task assignments (ambiguous ownership)
grep -A5 "assigned:" todo*.md 2>/dev/null | grep -E "assigned:.*,.*,"

# Verify TodoWrite completed count matches PROGRESS.md completed phases
echo "TodoWrite completed tasks:" && grep -c "status: completed" todo*.md 2>/dev/null
echo "PROGRESS.md completed phases:" && grep -c "\[x\]" PROGRESS.md 2>/dev/null

---

See Also

• `communication-protocols.md` — PROGRESS.md and STATUS.md sync patterns
• `preferred-patterns.md` — Parallel execution and file domain conflict patterns