scode-todo
Use this skill for two cases:
/scode-todo initin an empty repository.- Normal TODO work in a repository that already has
TODO.md,DONE.md, andT_max.md, or repo-localAGENTS.md/CLAUDE.mdfiles that say to always use$scode-todo.
The goal is simple: keep the repo-local agent instructions tiny, keep the workflow deterministic, and keep the VCS
operations behind bin/pull, bin/push, and bin/commit.
/scode-todo init is a one-time setup step. After that, the repository should already be configured to keep using this
skill without another explicit install step.
Init Workflow
When the user asks for /scode-todo init:
- Treat the repository as empty except for VCS metadata such as
.git,.sl, or.hg. - Ask which VCS preset to install:
git(standard git)graphitesaplingcustom
- For
sapling, ask for the remote bookmark to push to if it is notmain. Default tomain. - For
custom, ask for:- the shell command for
bin/pull - the shell command for
bin/push - the shell command for
bin/commit
- the shell command for
- For custom commit commands, require that the command already includes its own staging step and uses
$message(or${message}) where the commit message belongs. - Run
python3 scripts/init_todo_project.py --path <repo> --vcs <preset> ...from this skill. - Ensure the initialized repo contains both
AGENTS.mdandCLAUDE.md, each with the minimal instruction to always use$scode-todoin that repository. - After init, commit the scaffold if the repository is under version control and the user asked to initialize the repo. Do not auto-push init changes unless the user explicitly asks.
Read references/vcs-presets.md when the user wants to understand what each preset does or you need to justify the generated wrapper commands.
Working Files
The source of truth files are:
TODO.mdfor open tasksDONE.mdfor completed tasksT_max.mdfor the largest allocated numeric ID- optional
T-N.mdnotes files for long-form task notes
TODO.md must keep this shape:
# TODO
## Timed TODOs
- T-52[home,urgent]+ 2026-03-03 Take out the garbage
- T-54 2026-03-04 Call the insurance company
## Untimed TODOs
- T-53[errands]+ Replace bike tireRules:
- Timed entries are
T-N, optional[tags], optional+, thenYYYY-MM-DD, then the summary. - Timed TODOs stay sorted by due date ascending, then ID ascending.
- Untimed entries are
T-N, optional[tags], optional+, then the summary. - Untimed TODOs do not need a global sort beyond keeping the file stable.
DONE.md must keep this shape:
# DONE
## Completed TODOs
- T-52[home,urgent]+ 2026-03-03 Take out the garbage (done 2026-02-21)
- T-53[errands] Replace bike tire (done 2026-02-21)Rules:
- Keep each completed entry on one line.
- Preserve the original
TODO.mdline exactly, then append(done YYYY-MM-DD).
T_max.md is a plain integer. If you allocate a new TODO ID, update T_max.md in the same change.
T-N.md is optional. If it exists, the matching TODO line must carry a + marker immediately after the ID or tag
block.
ID, Tag, And Notes Rules
- TODO IDs are
T-<number>. - Numeric references like
52meanT-52when that is clearly the user's intent. - IDs are unique and never reused.
- Tags live immediately after the ID as
T-N[tag1,tag2]. - Tags are lowercase, deduplicated, sorted ascending, and contain no spaces.
- Notes live in
T-N.md. - The
+marker and the presence ofT-N.mdmust stay in sync. - When listing TODOs back to the user, preserve the inline ID, tags, and
+marker exactly as stored.
Natural Language Commands
Interpret requests like this:
Remind me to <task> at <DATE>creates a timed TODO.Remind me to <task> on mondaymeans the first upcoming Monday relative to today.- Relative dates like
tomorrowandin 2 daysare fine when they are unambiguous. - Normalize parsed dates to
YYYY-MM-DD. - If the user includes a bracketed tag list that is clearly metadata, treat it as tags instead of summary text.
- If the user includes
NOTES:, store everything after it inT-N.mdand add the+marker. NOTES:may be single-line or multi-line. Preserve the text faithfully.T-50 is donemarks that TODO complete.tag T-50 +fooadds a tag.tag T-50 -fooremoves a tag.- Natural-language tagging and notes edits should be honored when the target TODOs are unambiguous.
If a date is ambiguous, or an ID target is uncertain, ask before editing.
Completion Workflow
When a TODO is marked done:
- Find the matching entry in
TODO.md. - Remove it from
TODO.md. - Append the original line to
DONE.mdwith(done YYYY-MM-DD)using today's date. - Keep any matching
T-N.mdfile unless the user explicitly asks to remove it.
Repo Workflow
For an initialized TODO repo:
- Run
bin/pullfrom the repo root before making any user-requested modification. - If
bin/pullfails, stop and report the error. - Make only the edits required for the request.
- Commit the result after the requested change is complete.
Use the repo-local wrapper scripts as the source of truth for VCS operations.
NOTE: Repositories initialized by this skill use a three-step flow where bin/commit stages changes itself. Older
repositories may not. If the wrappers look pre-existing or behave differently, inspect them once and follow what they
actually do instead of assuming the generated preset behavior.
Commit and push rules:
- The user's exact requested change belongs in its own commit.
- If you also do formatting-only cleanup or reorganization, put that in a separate commit.
- Auto-push only when the changed files are limited to
TODO.md,DONE.md, andT-N.md. - Do not auto-push changes that touch
AGENTS.md,T_max.md,bin/*, skill files, docs, or other repo files unless the user explicitly asks. - If commit or push fails, report the error and ask what to do next.
Safety
- Be conservative. Change only what the user asked for.
- Do not delete data unless the user explicitly asks.
- Do not rewrite unrelated TODOs just because you touched the file.
- Never delete notes files unless the user explicitly asks.