todo-archive

TODO Archive

If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly; do not invoke this skill again through a skill tool.

Arguments

• path (optional): Repository root or any path inside the repository. Default to the current directory.
• --hint TEXT (optional): Archive only the section whose heading contains TEXT (case-insensitive substring), including its subsections. Without it, archive checked tasks from the whole file. Checked tasks outside the matched section stay in TODO.md.
• --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.

Workflow

1. Resolve the supplied path, or the current directory when omitted. For an existing file, use its containing directory; for a directory, use that directory. Store the absolute directory as start_dir, then resolve its Git root:

   git -C "$start_dir" rev-parse --show-toplevel
   

   Store the result as repo_root. When start_dir is outside a Git repository, use it as repo_root. Stop on a missing input path or another resolution error.

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

3. Resolve the skill directory and run its helper:

   uv run python "<skill-dir>/scripts/archive_todo.py" --root "$repo_root"
   

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

4. Report the rewritten TODO.md, the created or merged archive path, the matched section (when --hint was given), and the archived/remaining task counts. If an archive for the date already exists, the helper appends the new batch to it, retaining one matching top-level heading. If the helper reports no checked tasks, treat it as a no-op. If --hint matches no heading, the helper exits non-zero and lists the available sections; relay them.