From superpowers-plus
Archives completed and cancelled tasks from TODO.md into monthly archive files. Supports searching archived history and automatic archival based on age or file size.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-plus:todo-archiveThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Companion to:** `todo-management` (from superpowers-plus)
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:-}"
if command -v cb-env &>/dev/null; then
TODO_FILE_PATH=$(cb-env -- bash -c 'printf "%s" "$TODO_FILE_PATH"')
else
source ~/.codex/.env 2>/dev/null || true
fi
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 |
npx claudepluginhub bordenet/superpowers-plus --plugin superpowers-plusGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.