Manage Todo

Purpose

./todo.md

CRITICAL: Todo File Location

./todo.md

.claude/artifacts/YYYY-MM-DD/todos/todo-{name}.md

When to Use

Agent-Initiated (PRIMARY)

• "I need to create a todo to track this work"
• "User has given me multiple tasks to coordinate"
• "This is complex enough to warrant tracking"

User-Initiated

• "Create a todo for [feature]"
• "Update task [N] to [state]"
• "Track these tasks"

NOT to Use

• Single, straightforward tasks
• Trivial operations (<3 steps)
• Purely informational requests

Quick Start

Creating a Todo

1. Read project context
2. Create

   ./todo.md

   with structured tasks
3. Assign states (🔴 pending by default)
4. Add acceptance criteria
5. Sync with TodoWrite

Updating State

1. Read

   ./todo.md

2. Update task state: 🔴 → 🟡 → 🟢
3. Update TodoWrite to match
4. Update progress summary

Checking Progress

1. Read

   ./todo.md

2. Calculate completion %
3. Identify blockers
4. Suggest next actions

Basic Todo Structure

# Todo: [Feature Name]
Date: YYYY-MM-DD

## Objective
[Clear statement of goal]

## Tasks

### Task 1: [Title]
**Status:** 🔴 Not Started | 🟡 In Progress | 🟢 Complete
**Priority:** High | Medium | Low

**Description:**
What needs to be done.

**Acceptance Criteria:**
- [ ] Functionality implemented
- [ ] Tests pass
- [ ] Code follows conventions

## Progress Summary
- Total: X | Completed: Y (Z%)

Task States

Integration Requirements (CRITICAL)

The CCV Principle

Four Questions Test

1. How do I trigger this?
2. What connects it to the system?
3. What proves it runs?
4. What shows it works?

Three-Phase Todo Pattern

### Phase 1: CREATION
- [ ] Create [module]
- [ ] Unit tests pass

### Phase 2: CONNECTION
- [ ] Import in [consumer]
- [ ] Register in [system]
- [ ] Verify: `grep "module" src/`

### Phase 3: VERIFICATION
- [ ] Integration test passes
- [ ] Execution logs attached
- [ ] Expected outcome observed

Key Integrations

TodoWrite Synchronization

todo.md

Update todo.md → Update TodoWrite → Verify sync

Refactor/Migration Tracking

1. Detect refactor keywords
2. Invoke

   validate-refactor-adr

   skill
3. If no ADR: STOP, instruct user to create
4. If ADR exists: Use enhanced template

Task Sizing

• 1-4 hours of focused work
• Clear deliverable
• Single responsibility
• Testable outcome

Enforcement Rules

1. No Create Without Connect — Creation needs connection tasks
2. No Connect Without Verify — Connection needs verification
3. No Verify Without Evidence — Attach proof when checking
4. Phase 3 Blocks Completion — Cannot complete without runtime proof

Supporting Files

References

• references/reference.md - Task states, sync protocol, refactor tracking
• references/integration-requirements.md - CCV principle, patterns

Templates

• templates/todo-templates.md - Five use-case templates
• templates/refactor-todo-template.md - ADR-governed refactor
• templates/integration-verification-checklist.md - Integration verification

Examples

• examples/examples.md - Workflows and examples

Red Flags

Success Metrics