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.
TODO.md and .ai/ are conventionally git-ignored, so they are untracked and git diff shows nothing for them.
Inspect changes against the filesystem, not git.
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
Resolve the repository root:
git rev-parse --show-toplevel
If the command fails, use the provided path or current directory as the root.
Verify TODO.md exists at the root. If it is missing, stop and report the path checked.
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.
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.
If useful, inspect only the touched paths. TODO.md and .ai/ are git-ignored, so use the filesystem rather than
git diff:
cat TODO.md && find .ai/todos -type f | sort
Helper Behavior
scripts/archive_todo.py reads only <root>/TODO.md, writes archived tasks to <root>/.ai/todos/YYYY-MM/DD.md, and
rewrites <root>/TODO.md with the remaining tasks. It preserves task-free sections and prose verbatim (a minimal
# TODO stub only if everything was archived). With --hint, it restricts archiving to the matched heading's subtree
and exits non-zero listing available headings when nothing matches. A same-day re-run appends its batch to that day's
file, removing the new leading H1 only when it exactly matches the existing archive's leading H1.
Completion
Completion evidence is the helper's archive path plus archived and remaining task counts; a no-checked-task result is a
successful no-op. Dry-run completion requires rendered paths/content with no filesystem changes, but the final message
still follows the one-line formats below. Report the result as a single line (append a (scope: "<hint>") segment only
when --hint was given), with the archive path relative to the repository root:
- Success:
📦 Archived <n> → <archive path> (created|merged) · <remaining> remaining
- No-op:
✅ Nothing to archive · <remaining> remaining
- Dry run:
🔎 Would archive <n> → <archive path> (would create|would merge) · <remaining> would remain
Do not repeat full dry-run document content in the final message or add decoration to TODO/archive files, paths,
commands, or helper diagnostics.
1---2name: todo-archive3description: Archive checked TODO.md tasks into `.ai/todos/YYYY-MM/DD.md`, leaving unchecked tasks.4---5
6# TODO Archive
7
8If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly;
9do not invoke this skill again through a skill tool.
10
11`TODO.md` and `.ai/` are conventionally git-ignored, so they are untracked and `git diff` shows nothing for them.
12Inspect changes against the filesystem, not git.
13
14## Arguments
15
16- `path` (optional): Repository root or any path inside the repository. Default to the current directory.
17- `--hint TEXT` (optional): Archive only the section whose heading contains `TEXT` (case-insensitive substring),
18 including its subsections. Without it, archive checked tasks from the whole file. Checked tasks outside the matched
19 section stay in `TODO.md`.
20- `--date YYYY-MM-DD|YYYY_MM_DD` (optional): Archive date. Default to today's local date.
21- `--dry-run` (optional): Preview target paths and rendered content without writing.
22
23## Workflow
24
251. Resolve the repository root:
26
27 ```sh
28 git rev-parse --show-toplevel
29 ```
30
31 If the command fails, use the provided `path` or current directory as the root.
32
332. Verify `TODO.md` exists at the root. If it is missing, stop and report the path checked.
34
353. Resolve the skill directory and run its helper:
36
37 ```sh
38 uv run python "<skill-dir>/scripts/archive_todo.py" --root "$repo_root"
39 ```
40
41 Pass through `--hint`, `--date`, or `--dry-run` when the user requested them.
42
434. Report the rewritten `TODO.md`, the created or merged archive path, the matched section (when `--hint` was given),
44 and the archived/remaining task counts. If an archive for the date already exists, the helper appends the new batch
45 to it, retaining one matching top-level heading. If the helper reports no checked tasks, treat it as a no-op. If
46 `--hint` matches no heading, the helper exits non-zero and lists the available sections; relay them.
47
485. If useful, inspect only the touched paths. `TODO.md` and `.ai/` are git-ignored, so use the filesystem rather than
49 `git diff`:
50
51 ```sh
52 cat TODO.md && find .ai/todos -type f | sort
53 ```
54
55## Helper Behavior
56
57`scripts/archive_todo.py` reads only `<root>/TODO.md`, writes archived tasks to `<root>/.ai/todos/YYYY-MM/DD.md`, and
58rewrites `<root>/TODO.md` with the remaining tasks. It preserves task-free sections and prose verbatim (a minimal
59`# TODO` stub only if everything was archived). With `--hint`, it restricts archiving to the matched heading's subtree
60and exits non-zero listing available headings when nothing matches. A same-day re-run appends its batch to that day's
61file, removing the new leading H1 only when it exactly matches the existing archive's leading H1.
62
63## Completion
64
65Completion evidence is the helper's archive path plus archived and remaining task counts; a no-checked-task result is a
66successful no-op. Dry-run completion requires rendered paths/content with no filesystem changes, but the final message
67still follows the one-line formats below. Report the result as a single line (append a `(scope: "<hint>")` segment only
68when `--hint` was given), with the archive path relative to the repository root:
69
70- Success: `📦 Archived <n> → <archive path> (created|merged) · <remaining> remaining`
71- No-op: `✅ Nothing to archive · <remaining> remaining`
72- Dry run: `🔎 Would archive <n> → <archive path> (would create|would merge) · <remaining> would remain`
73
74Do not repeat full dry-run document content in the final message or add decoration to TODO/archive files, paths,
75commands, or helper diagnostics.
gabrielmoreira