Use when capturing tasks, tracking work, triaging priorities, querying task history, or executing multi-step plans.
Wrong skill? Archiving completed tasks →
todo-archive. Plan execution →plan-and-execute.File location: Resolved from
TODO_FILE_PATHin~/.codex/.env(falls back to$HOME/.codex/TODO.md) PRD: SeePRD.mdin this skill folder for full requirements MCP Tools:add_tasks,update_tasks,view_tasklist(for in-conversation tracking)
For 3+ step plans, use (PRIMARY, survives crashes/compaction) + (supplementary, session-only UI). Write TODO.md first, then mirror to MCP.
config-refactor). Ask if ambiguous.#plan-<identifier> tag in TODO.mdadd_tasks with parent_task_id#plan-<identifier> to check completiontodo-crud.shUse todo-crud.sh for ALL TODO.md access — both reading and writing. It resolves the correct path from ~/.codex/.env automatically. NEVER cat or view TODO.md directly.
# READ — show TODO.md contents (resolved path)
~/.codex/superpowers-plus/tools/todo-crud.sh cat
~/.codex/superpowers-plus/tools/todo-crud.sh path # just the path
~/.codex/superpowers-plus/tools/todo-crud.sh list # filtered task list
# WRITE — add, complete, move, defer
~/.codex/superpowers-plus/tools/todo-crud.sh add --priority P3 --description "Task description" --tags "#tag1 #tag2" --note "Additional context"
~/.codex/superpowers-plus/tools/todo-crud.sh complete --id 20260322-01 --note "Resolution notes"
~/.codex/superpowers-plus/tools/todo-crud.sh move --id 20260322-01 --to P1
~/.codex/superpowers-plus/tools/todo-crud.sh defer --id 20260322-01 --reason "Blocked on X"
# Multi-agent: claim a task (marks [/], adds TTL metadata)
~/.codex/superpowers-plus/tools/todo-crud.sh claim --id 20260322-01 --ttl 30
~/.codex/superpowers-plus/tools/todo-crud.sh unclaim --id 20260322-01
~/.codex/superpowers-plus/tools/todo-crud.sh reap
# Utility
~/.codex/superpowers-plus/tools/todo-crud.sh next-id
~/.codex/superpowers-plus/tools/todo-crud.sh --json list --all
What it does automatically: path resolution, advisory locking, backup before write, task ID allocation, section targeting, whitespace normalization, expired claim reaping. Cross-platform (macOS + Linux).
If TODO.md doesn't exist: Run todo-preflight.sh --create-if-missing first to create from template.
todo-maintenance.shUse todo-maintenance.sh for routine housekeeping. It resolves/creates TODO.md, reports stale #plan-* tasks, and runs archive automatically when housekeeping thresholds are hit.
# One-command maintenance (recommended after multi-step sessions)
~/.codex/superpowers-plus/tools/todo-maintenance.sh
# Preview housekeeping actions without modifying TODO.md
~/.codex/superpowers-plus/tools/todo-maintenance.sh --dry-run
# Machine-readable summary for agents/scripts
~/.codex/superpowers-plus/tools/todo-maintenance.sh --json
| Tool | When to use |
|---|---|
todo-preflight.sh | Create initial TODO.md, or debug path resolution |
todo-lock.sh | Debug lock issues (status, steal commands) |
NEVER write to TODO.md except through the approved TODO tools (todo-crud.sh, todo-preflight.sh --create-if-missing, todo-maintenance.sh). This ban includes:
save-file / str-replace-editor / echo > / cat > / sed -i / inline pythonIncident 2026-03-23: An agent used save-file to overwrite TODO.md with a raw task list. Dozens of unstarted tasks were permanently destroyed. No backup was created. Recovery was impossible.
todo-crud.sh prevents this by: (1) resolving the correct TODO_FILE_PATH, (2) acquiring an advisory lock, (3) creating a timestamped backup, (4) validating section structure (required headers in order, priority subsections, and at least one task or history artifact). Bypassing it bypasses ALL of these protections.
todo-engine.py)| Layer | Mechanism | What it catches |
|---|---|---|
| 1. Rules | This ban + AGENTS.md + core.always.md | Cooperating agents |
| 2. Structural validation | validate_structure() in write_file() | Malformed content through engine |
| 3. OS immutability | chflags uchg (macOS) / chattr +i (Linux) | ALL direct writes — Operation not permitted |
| 4. chmod 444 | Secondary protection if immutability unavailable | save-file, str-replace-editor, shell redirects |
| 5. Shadow + annihilation | Pre-write comparison vs shadow | Catastrophic data loss (>60% size drop, all tasks wiped, >5 tasks lost) |
| 6. Stray path detection | _validate_canonical_path() in write_file() | Writes to wrong TODO.md path |
| 7. Path obscuring | Path in private .todo-registry, NOT in .env | Agent path discovery; honeypot at ~/.codex/TODO.md |
If annihilation detection blocks a legitimate write: delete ~/.codex/todo-shadow/TODO.md and retry.
Incidents:
save-file to overwrite TODO.md, destroying dozens of open tasks. Unrecoverable.~/.codex/TODO.md — stray file. Fix: _validate_canonical_path().chflags uchg + path obscuring + honeypot.When multiple agents (Augment, Claude Code, amp, etc.) share a TODO.md, use claim/unclaim/reap to prevent duplicate work:
claim --id <ID> — marks [/] with TTL metadatacomplete --id <ID> — moves to HISTORY (claim auto-removed)unclaim --id <ID> — reverts to [ ] for another agentreap — finds expired claims and reverts themTTL (default 30 min): If an agent claims a task and dies/disconnects, the claim expires after TTL minutes. Another agent running claim or reap will auto-reap it.
Agent identity: Set AGENT_ID env var for readable names. Falls back to hostname:ppid.
Claim metadata (single line in task block):
- Claimed: 2026-03-25T14:30:00 by augment-session-1 ttl=30
Use claim --id <ID> → complete --id <ID> (or unclaim to abandon). Claims auto-expire after TTL (default 30 min). Run reap to clean expired claims. Set AGENT_ID env var for readable names.
Conversational TODO management. Captures tasks in ≤15 seconds, P1/P2/P3 priority, auto-tagged. Commands: "Add task: X", "Show my tasks", "Complete [ID]", "What did I do?", "What should I work on?", "Triage".
| Priority | Label | Max | Definition |
|---|---|---|---|
| P1 | Today | 5 | Must complete today; blocking others or time-sensitive |
| P2 | This Week | 15 | Should complete this week; important but flexible |
| P3 | Backlog | ∞ | Complete when capacity allows |
P1 Overload: If P1 count > 5, warn: "You have [N] P1s. That's unsustainable—want to demote any?"
#plan-<id> for parallel work. Full taxonomy: references/taxonomy.mdreferences/file-format-and-operations.md (sections, IDs, operations, lock workflow)references/context-aware-standard.md — enforce on #plan-* tasksP1 >5 → warn/demote. P3 >14 days → Friday sweep. Multi-day → ask progress. Plan tasks without Context-Aware fields → warn.
Housekeeping: Move [x] to HISTORY immediately. Run todo-maintenance.sh after multi-step sessions.
| Failure | Detection | Recovery |
|---|---|---|
| Direct file write attempted | OS immutability blocks it | No action needed |
| Honeypot tampered/missing flag | sp-doctor Check 23 detects | Run sp-doctor --fix |
| TODO path missing | Check 24 reports ERROR | Run todo-preflight.sh --create-if-missing |
.todo-registry missing/empty | self-test warns; falls back to .env → default path | Create .todo-registry with real TODO path |
| Annihilation detected (>60% drop) | Engine blocks write | Delete ~/.codex/todo-shadow/TODO.md and retry |
| Lock stuck (agent died mid-write) | TTL expires after 120s | Wait 2 min, or rm -rf the .TODO.md.lock dir |
| Agent writes directly despite rules | Shadow comparison catches post-write | Restore from ~/.codex/todo-shadow/TODO.*.bak |
Honeypot is optional. Only for external TODO paths. Default-path users: no honeypot, Check 23 auto-skips.
Backup: todo-crud.sh creates a timestamped backup before every write. The archive subsystem (invoked by todo-maintenance.sh) also creates its own backup before modifying the file.
| Failure | Detection | Recovery |
|---|---|---|
Agent uses save-file/str-replace-editor on TODO.md | OS immutability (uchg/chattr +i) blocks the write with "Operation not permitted" | No action needed — write was prevented |
Agent bypasses to ~/.codex/TODO.md (honeypot) | Honeypot is also uchg+444; sp-doctor Check 23 detects content tampering | Run sp-doctor --fix to restore honeypot |
| Honeypot immutable flag removed | todo-crud.sh self-test and sp-doctor Check 23 detect missing flag | Run sp-doctor --fix (macOS: chflags uchg, Linux: sudo chattr +i) |
.todo-registry missing or empty | todo-crud.sh self-test warns; engine falls back to .env → default path | Create .todo-registry with real TODO path |
| TODO path points to nonexistent file | sp-doctor Check 24 reports ERROR | Run todo-preflight.sh --create-if-missing |
| Annihilation detection blocks write | Engine detects >60% size drop or >5 task loss | Delete ~/.codex/todo-shadow/TODO.md and retry |
| Lock stuck (agent died mid-write) | Lock TTL expires after 120s; next operation auto-reaps | Wait 2 min, or manually rm -rf the .TODO.md.lock dir |
| Agent writes directly despite rules | Shadow comparison catches post-write; sp-doctor catches honeypot damage | Restore from ~/.codex/todo-shadow/TODO.*.bak |
Honeypot is optional. The honeypot at
~/.codex/TODO.mdis only deployed when the real TODO lives elsewhere (e.g., OneDrive, Dropbox, a shared repo). If yourTODO_FILE_PATHpoints to~/.codex/TODO.md(the default), no honeypot exists and Check 23 is automatically skipped. The honeypot rows above only apply to users who configured an external TODO path.
# Full health check
~/.codex/superpowers-plus/tools/todo-crud.sh self-test
# Doctor checks (23: honeypot, 24: path validation, 25: stale workflow)
bash ~/.codex/superpowers-plus/tools/doctor-checks.sh