todo-archive

argument-hint	[path] [--date YYYY-MM-DD|YYYY_MM_DD] [--dry-run] [--force]
disable-model-invocation	false
name	todo-archive
user-invocable	true
description	Use only when explicitly asked to archive/prune/compact/roll over checked tasks from TODO.md into `.ai/todos/TODO_UNTIL_YYYY_MM_DD.md`, leaving unchecked tasks.

TODO Archive

Archive checked Markdown task-list items from TODO.md into .ai/todos/TODO_UNTIL_YYYY_MM_DD.md, then leave only unchecked tasks in TODO.md.

Arguments

• path (optional): Repository root or any path inside the repository. Default to the current directory.
• --date YYYY-MM-DD|YYYY_MM_DD (optional): Archive date. Default to today's local date.
• --dry-run (optional): Preview target paths and rendered content without writing.
• --force (optional): Overwrite the date-only archive in place instead of rolling a same-day re-run over to a timestamped file.

Workflow

1. Resolve the repository root:

   git rev-parse --show-toplevel
   

   If the command fails, use the provided path or current directory as the root.

2. Verify TODO.md exists at the root. If it is missing, stop and report the path checked.

3. Run the helper from this skill directory:

   uv run python scripts/archive_todo.py --root "$repo_root"
   

   Pass through --date, --dry-run, or --force when the user requested them.

4. Report the rewritten TODO.md, the created archive path, and the checked/unchecked task counts. If an archive for the date already exists, the helper rolls the new batch over to TODO_UNTIL_YYYY_MM_DD_HHMM.md and keeps the earlier file; report both paths. If the helper reports no checked tasks, treat it as a no-op.

5. If useful, inspect only the touched paths:

   git diff -- TODO.md .ai/todos/
   

Helper Behavior

scripts/archive_todo.py:

• Reads only <root>/TODO.md.
• Writes checked tasks to <root>/.ai/todos/TODO_UNTIL_YYYY_MM_DD.md.
• Rewrites <root>/TODO.md with unchecked tasks.
• Preserves non-task content inside any heading subtree that still has tasks for the output.
• Drops headings whose subtree has no tasks for the output.
• Keeps nested parent items as plain bullets when only descendants match the output, avoiding orphaned subtasks without copying the wrong checkbox state.
• Leaves a minimal # TODO stub when every task was archived.
• Rolls a same-day re-run over to a timestamped TODO_UNTIL_YYYY_MM_DD_HHMM.md sibling (appending a counter on a same-minute collision) so an earlier batch is never clobbered.
• Overwrites the date-only archive in place only when --force is passed.