From superpowers-plus
Archives completed and cancelled tasks from TODO.md HISTORY section to monthly markdown files in todo-archives/. Searches archived tasks by keyword or date. Use for TODO cleanup when file exceeds 400 lines or entries over 7-30 days old.
npx claudepluginhub bordenet/superpowers-plus --plugin superpowers-plusThis skill uses the workspace's default tool permissions.
> **Companion to:** `todo-management` (from superpowers-plus)
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.
Companion to:
todo-management(from superpowers-plus) Archive location:$(dirname $TODO_FILE_PATH)/todo-archives/Index:todo-archives/INDEX.mdWrong skill? Managing active tasks →
todo-management. Task CRUD operations → usetodo-crud.shdirectly.
| Trigger | Action |
|---|---|
| User says "archive todos" | Run full archive of all HISTORY entries |
Routine housekeeping run via todo-maintenance.sh | Use this archive engine when maintenance thresholds trigger |
| TODO.md exceeds 400 lines | Auto-archive HISTORY entries ≥7 days old |
| HISTORY has entries >30 days old | Archive regardless of line count (staleness rule) |
| User says "search archived todos for X" | Search across archive files |
| User says "show archived todos from Month Year" | Display specific monthly archive |
EXPLICIT_TODO_FILE_PATH="${TODO_FILE_PATH:-}"
source ~/.codex/.env 2>/dev/null
TODO_FILE_PATH="${EXPLICIT_TODO_FILE_PATH:-${TODO_FILE_PATH:-$HOME/.codex/TODO.md}}"
TODO_PATH="${TODO_FILE_PATH:-$HOME/.codex/TODO.md}"
ARCHIVE_DIR="$(dirname "$TODO_PATH")/todo-archives"
Parse the # HISTORY section of TODO.md. Identify completed ([x]) and cancelled ([-]) tasks.
Archival criteria (any match triggers archival):
archive todos) → archive ALL HISTORY entriesFor each task, extract the Done: or Cancelled: date. Compute target file: YYYY-MM.md.
For each target month file:
If file doesn't exist → create with header:
# TODO Archive — {Month Name} {Year}
> Tasks archived from TODO.md
Check for duplicate task IDs (idempotency guard) and skip re-appending blocks already present in the month file
Append tasks under ## YYYY-MM-DD date headers (reverse-chronological)
Compute and add metadata: Duration:, Issue: (extract ticket IDs from tags/description)
Rebuild INDEX.md from all archive files:
# TODO Archive Index
> Total archived: {count} tasks across {n} months
| Month | Tasks | Top Tags | Related Issues |
|-------|-------|----------|---------------|
| 2026-03 | 42 | #engineering (18) | PROJ-$1, PROJ-$1 |
| 2026-02 | 38 | #recruiting (12) | PROJ-$1 |
Remove only the archived entries from the HISTORY section. Keep any entries that didn't meet archival criteria.
pre_history_count = {N}
removed_from_history = {M}
post_history_count = {N - M}
If mismatch → ABORT, restore from backup, report error.
# TODO Archive — March 2026
> Tasks archived from TODO.md
## 2026-03-18
- [x] [20260315-01] Fix alarm tuning across repos #engineering-backend
- Added: 2026-03-15
- Done: 2026-03-18T14:30:00
- Duration: 3 days
- Progress: Tuned P1/P2 alarms, added runbook URLs
- Issue: PROJ-$1
## 2026-03-15
- [x] [20260314-02] Review config PR #engineering-backend
- Added: 2026-03-14
- Done: 2026-03-15T10:30:00
- Duration: 1 day
- Progress: Approved with minor suggestions
search archived todos for "alarm tuning"
→ grep -rn "alarm tuning" "$ARCHIVE_DIR"/*.md
search archived todos for PROJ-$1
→ grep -rn "PROJ-$1" "$ARCHIVE_DIR"/*.md
show archived todos from March 2026
→ cat "$ARCHIVE_DIR/2026-03.md"
show archived todos from 2026-02-01 to 2026-03-15
→ cat 2026-02.md 2026-03.md (then filter by date headers)
todo-lock.sh (future improvement)| Scenario | Resolution |
|---|---|
| Task completed then re-opened | Archive entry stays (immutable). New ACTIVE entry with Reopened from [ID] |
| Concurrent archive attempts | Not yet guarded — avoid running concurrently with todo-crud.sh |
| Archive file already has entries for that day | Append under existing date header (no duplicate header) |
| HISTORY section is empty | No-op, report "No completed tasks to archive" |
| No HISTORY section exists | No-op, report "No HISTORY section found" |
| Failure | Fix |
|---|---|
| Concurrent write with todo-crud.sh corrupts archive | Use locking — abort if TODO.md is locked |
| Losing task metadata (tags, issue links) during archival | Verify archived block matches source block character-for-character |
| Archive runs during active task operations — split-brain | Check for in-progress tasks before archiving; warn user |
| Count mismatch after archive but error suppressed | Hard abort + restore from backup on ANY integrity mismatch |