Index of every page on this site: llms.txt
All skills
scode avatar

/scode-todo

@03a9f7f
Run it yourself

Use only when the user explicitly invokes `/scode-todo` or `$scode-todo`.

  • 5 files
  • 19.2 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/scode-todo

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈21 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈1.7k more on demand in 3 files.

Description uses 1.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈86 characters, or 1.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

scode-todo

Use this skill for two cases:

  1. /scode-todo init in an empty repository.
  2. Normal TODO work in a repository that already has TODO.md, DONE.md, and T_max.md, or repo-local AGENTS.md / CLAUDE.md files 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:

  1. Treat the repository as empty except for VCS metadata such as .git, .sl, or .hg.
  2. Ask which VCS preset to install:
    • git (standard git)
    • graphite
    • sapling
    • custom
  3. For sapling, ask for the remote bookmark to push to if it is not main. Default to main.
  4. For custom, ask for:
    • the shell command for bin/pull
    • the shell command for bin/push
    • the shell command for bin/commit
  5. For custom commit commands, require that the command already includes its own staging step and uses $message (or ${message}) where the commit message belongs.
  6. Run python3 scripts/init_todo_project.py --path <repo> --vcs <preset> ... from this skill.
  7. Ensure the initialized repo contains both AGENTS.md and CLAUDE.md, each with the minimal instruction to always use $scode-todo in that repository.
  8. 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.md for open tasks
  • DONE.md for completed tasks
  • T_max.md for the largest allocated numeric ID
  • optional T-N.md notes 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 tire

Rules:

  • Timed entries are T-N, optional [tags], optional +, then YYYY-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.md line 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 52 mean T-52 when 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 of T-N.md must 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 monday means the first upcoming Monday relative to today.
  • Relative dates like tomorrow and in 2 days are 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 in T-N.md and add the + marker.
  • NOTES: may be single-line or multi-line. Preserve the text faithfully.
  • T-50 is done marks that TODO complete.
  • tag T-50 +foo adds a tag.
  • tag T-50 -foo removes 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:

  1. Find the matching entry in TODO.md.
  2. Remove it from TODO.md.
  3. Append the original line to DONE.md with (done YYYY-MM-DD) using today's date.
  4. Keep any matching T-N.md file unless the user explicitly asks to remove it.

Repo Workflow

For an initialized TODO repo:

  1. Run bin/pull from the repo root before making any user-requested modification.
  2. If bin/pull fails, stop and report the error.
  3. Make only the edits required for the request.
  4. 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, and T-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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago

README badge

README badge for scode/dotfiles/scode-todo