todo
Use when generating or resuming TODO.md from PLAN.md, reporting task state, handling blocked, skipped, temporary, or dependent items, recording CHANGELOG.md, or continuing tracked work across sessions.
LeaveAsien · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add LeaveAsien/smart-todo-flow --skill todo技能说明
name: todo description: >- Use when generating or resuming TODO.md from PLAN.md, reporting task state, handling blocked, skipped, temporary, or dependent items, recording CHANGELOG.md, or continuing tracked work across sessions.
Smart TODO Flow
Manage work through PLAN.md -> TODO.md -> CHANGELOG.md.
Core principle: persistent memory, resumable, user controls the pace.
State Detection
On every invocation, detect state by priority:
- User explicitly says "clear todo" -> clear
TODO.md TODO.mdexists with unchecked items ([ ]) -> enter Resume ModeTODO.mdexists and all items are resolved ([x],[-],[~]; no[ ]) -> enter Completion PendingTODO.mdis missing or empty -> enter Generation Mode
If the user explicitly asks to write the changelog or archive work, enter the relevant changelog flow even if another state applies.
Task States
TODO items support four states:
| Syntax | State | Meaning |
|---|---|---|
- [ ] | Pending | Not started |
- [x] | Done | Completed |
- [-] | Blocked | Cannot proceed; reason noted inline |
- [~] | Skipped | Intentionally deferred |
Blocked and skipped items use inline notes:
- [-] Deploy to production (blocked: waiting for security review)
- [~] Write integration tests (skipped: API spec not finalized)
Resume Mode
Smart Detection of Completed Work
If the project is a git repository, inspect recent commits and the current diff:
git log --oneline -10git diff --stat
Compare them against unchecked TODO items. If an item appears addressed, suggest marking it done but never update it without user confirmation. Skip this step outside git repositories.
Detected: recent commits may have addressed these items:
- [ ] Implement user auth -> commit a1b2c3d "add user auth middleware"
Mark as done? (y/n per item)
Progress Report
Read TODO.md and report progress with a state breakdown. Use TODO.md as the primary state source. Read PLAN.md only when the phase marker, next-phase decision, or plan/task ambiguity requires it.
Phase: 2 (from PLAN.md)
Progress: 3/7 done · 1 blocked · 1 skipped · 2 remaining
Blocked:
- [-] Task B (blocked: reason)
Skipped:
- [~] Task F (skipped: reason)
Remaining:
- [ ] Task D
- [ ] Task E
How would you like to proceed? (e.g.: do next item / finish all / do item 5 first / I'll pick)
Omit the Phase line when no <!-- phase: N --> marker exists.
Runtime Integration
Before starting an execution item, read references/runtime.md when it exists.
Use that adapter only for ephemeral session progress; TODO.md remains the durable source of truth.
If the adapter capability is unavailable, continue without the session mirror.
Generation Mode
Information Gathering
Use project instructions already available in the current context. Read the relevant instruction files only when that context is missing or insufficient. Then gather the remaining generation context:
PLAN.mdfor goals and phase planning- Current code state, including
git statusand recent commits when git is available
When PLAN.md Does Not Exist
Ask the user:
No PLAN.md found in this project. How should we proceed?
1. I'll draft a quick one based on project instructions and current project state
2. You generate one yourself
3. No PLAN needed - just tell me what to do
PLAN Guidance
When the user's input looks like it might contain planning-level content, offer a choice instead of deciding for the user:
These could be planning directions or action items - you know best:
1. Write to PLAN.md first, then pick items to generate TODO
2. Directly generate TODO from these
Which way?
Planning-level content includes multiple directions, feature ideas, architectural options, phased goals, or vision-level discussion.
Phase Detection
When reading PLAN.md:
- Look for phase or stage structure, such as
Phase 1,Stage A,第一阶段, or numbered sections - If
TODO.mdpreviously existed with<!-- phase: N -->, identify the next phase - If no prior phase marker exists, start from the first phase with unfinished goals
- Present the detected phase to the user for confirmation before generating
Generating TODO
- Break down current phase goals into concrete, actionable steps
- Default to 5-8 steps; adjust if the user asks for finer or coarser granularity
- If tasks have natural ordering dependencies, annotate with
(depends: N)whereNis the item number - Present the TODO draft for confirmation; write
TODO.mdonly after approval - If the user modifies the draft, adjust and re-confirm
TODO.md format:
# TODO
<!-- phase: 1 -->
- [ ] First step description
- [ ] Second step description
- [ ] Third step description (depends: 2)
Keep TODO.md as a pure checklist: no dates, section headers, or priority fields beyond the phase comment.
Execution
User Options
The user may:
- Specify one or several items to work on
- Say "next" to do one item
- Say "finish all" to execute all remaining items in one turn
- Pick a custom order
- Mark an item as blocked: "item 3 is blocked because..."
- Mark an item as skipped: "skip item 4"
Default pacing: after completing each item, pause, report progress, and wait for user input before continuing. "finish all" opts into a longer continuous turn with higher token usage.
Dependency Check
When the user selects a task, check for (depends: N). If a dependency is not [x], warn the user and ask whether to proceed anyway or do the dependency first.
Starting a Task
When the user selects a task:
- Re-read relevant project instructions when needed
- Read
references/runtime.mdwhen it exists - Use the runtime adapter to mark the selected item in progress when that capability is available
- Implement the task
If the user marks an item blocked or skipped instead of implementing it, update TODO.md