todo-archive

TODO Archive

If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that case, 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 .ai/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 .ai/TODO.md exists under 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 .ai/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. In that case, relay them.