notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/project-coordinator/todowrite-integration.md
View on GitHub# 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.
```markdown
Task: "Phase 1: Generate database schema"
id: phase-1-schema
status: in_progress
assigned: db-worker (data/database.md)
output: schema.sql
Task: "Phase 2: ORM models"
id: phase-2-models
status: pending
blockedBy: phase-1-schema
assigned: python-worker (programming/python-general.md)
output: src/models/*.py
Task: "Phase 3: API endpoints"
id: phase-3-api
status: pending
blockedBy: phase-2-models
assigned: api-worker (programming/nodejs-api.md)
output: src/routes/*.js
Task: "Phase 4: Integration tests"
id: phase-4-tests
status: pending
blockedBy: phase-3-api
assigned: api-worker (programming/nodejs-api.md), python-worker (programming/python-general.md) (parallel)
output: tests/integration/*
```
---
### Completion Verification Before Status Update
Never mark `completed` based on agent claim alone — verify with success criteria first.
```markdown
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.
```markdown
Task: "Phase 4: Integration tests (parallel)"
id: phase-4-tests
status: in_progress
blockedBy: phase-3-api
parallel_agents:
- agent: api-worker (programming/nodejs-api.md)
files: tests/integration/api/*.test.js
id: phase-4a-api-tests
- agent: python-worker (programming/python-general.md)
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**:
```bash
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:
```markdown
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**:
```bash
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**:
```bash
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
```bash
# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |