From superpowers-plus
Manages TODO tasks via persistent TODO.md file and todo-crud.sh bash script: capture, track, triage priorities, query history, execute multi-step plans with MCP mirroring.
npx claudepluginhub bordenet/superpowers-plus --plugin superpowers-plusThis skill uses the workspace's default tool permissions.
> **Wrong skill?** Archiving completed tasks → `todo-archive`. Plan execution → `plan-and-execute`.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
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 TODO.md (PRIMARY, survives crashes/compaction) + MCP tools (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
References: references/taxonomy.md · references/file-format-and-operations.md