todo-manager

Todo Manager Skill

Core Capabilities

• Status Sync: Update task statuses (in progress, completed) in docs/plan/todo.md in real time.
• Task Breakdown: Break down complex requirements into atomic items in todo.md .
• Version Planning: Update docs/plan/roadmap.md。
• Item Triage Destinations: Place newly added items into the current phase or backlog based on priority, rather than always stuffing them into the current to-do list.
• Closed-Loop Check: Before a task is completed, verify whether all TODO items have been checked off.
• Phase Archive Wrap-Up: At the end of a phase, clean up todo.md, update todo-archive.md, sync roadmap.md and the multilingual roadmap summary according to a unified checklist.
• Session-Level Task Protocol Management: Maintain .session/current-task.yaml, restore context at the start of a session, and update progress and cognitive state at the end of a session.

Instructions

1. Path Awareness: Planning-related operations (todo.md, roadmap.md) should be executed under the project main root directory (master branch).
2. Triage Before Writing: Before newly discovered items are written to todo.md or roadmap.md , they must first go through requirement-analyst or an equivalent process to determine whether they belong to the current scope, are allowed to jump the queue, or are deferred items.
3. Start and End Correspondence: Before each task starts, the corresponding TODO must be marked as in-progress; after completion, mark it as completed。
4. No Unthresholded Expansion: Do not directly append multiple new items to the current phase just because problems were discovered incidentally during development. Only high-priority items such as delivery blockers, regression fixes, and security/compliance fixes may be inserted into the current phase.
5. Deferred Items Have a Place to Go: Low-priority items must not simply be ignored; experience optimizations, non-blocking dependency upgrades, exploratory ideas, etc. should be written to the backlog area of roadmap.md , rather than consuming current iteration capacity.
6. Capacity Constraint: If the number of core tasks in the current phase will exceed 5-6 items, prompt execution of the "one in, one out" strategy.
7. Document Consistency: Ensure roadmap.md stays in sync with actual development progress.
8. Single Source of Truth for the Archive Process: Anything involving "phase completion, archiving, switching to the next phase" must strictly follow the "Standard Process for Phase Archiving and Next Phase Planning" in docs/standards/planning.md , and must not omit checklist items or change the order on its own.
9. Pre-Archive Check: Before archiving, it must be confirmed item by item that the current phase items are completed,todo.md that currently in-progress items have been cleared, that regression records and quality gate evidence are traceable, and that there is at least one round of review conclusions.
10. Archive Update Order: First clean up todo.md, then write todo-archive.md, then sync roadmap.md, and finally update docs/i18n/*/plan/roadmap.md；todo.md and backlog.md as needed; by default, keep Chinese and do not translate separately for the archive action.
11. Minimum checks must not be skipped: Stage archival is a formal planning change, and at minimum must include lint-md、pnpm docs:check:i18n, quality gate status confirmation, and error surface checks; if these pieces of evidence are missing, it must not be marked "archived".
12. Next-stage gate: Before the current stage is archived, only "candidate options / admission analysis" may be output, and the next stage must not be written directly into todo.md or roadmap.md。

Session-level task protocol management

.session/current-task.yaml is the session-level supplement to the stage-level todo.md .todo.md is responsible for the stage span (in weeks), and.session/current-task.yaml is responsible for the session span (in hours). Synchronizing the two does not replace either.

Session startup recovery

At the start of each new session (whether it is a new conversation window or continuing after a task switch), restore context in the following order:

1. Read .session/current-task.yaml → obtain the active_plan、progress(completed / in progress / blocked),next_steps , and cognitive status.
2. Read .session/runtime-state.json → obtain failure_count、active_mode、last_verification。
3. Read .session/wisdom.md → if there are findings worth reusing across sessions, load them as well.
4. Read docs/plan/todo.md → align the stage-level context, and confirm whether the currently in-progress main line is consistent with the session protocol.

Session closing update

Before the end of each session (when the user says "wrap up", "end", "that's it for today", or actively switches tasks), update .session/current-task.yaml：

Field	Update content
progress.completed	Append the specific steps completed in this session
progress.in_progress	Update the currently in-progress step (at most one item)
progress.blocked_on	If there is a blocker, state the reason (otherwise leave blank)
next_steps	Priorities for the next session (no more than 3 items)
cognitive	Update only if there was a failure in this session (failure_count、active_mode、tried_approaches、switched_from）
session.updated_at	Update to the current time

In addition:

• If there is a pattern / bug / decision worth reusing across sessions, append it to .session/wisdom.md。
• Update the .session/runtime-state.json of last_verification。

Key boundaries

• .session/ The directory is git-ignored, does not enter the version repository, does not enter deep archiving, does not enter the semantic index.
• The session protocol istask state(rewritten each session), not historical state. At the end of a stage, there is no need to archive the .session/ content into todo-archive.md。
• If .session/current-task.yaml does not exist (new project or first use), initialize it according to the normal process: derive the initial content from the currently in-progress items in todo.md .

Usage Example

Action: Read todo.md, find the highest-ranked task that has not yet started, start the development process, and mark that item as "in development".

Action: When a non-blocking experience optimization point is discovered during development, do not add it directly to the current stage; instead, add it to the backlog of roadmap.md , and note the source context.

Action: When all main lines of the current stage are complete, first check archival admission, regression evidence, Review Gate, and documentation synchronization according to planning.md , then update todo.md、todo-archive.md、roadmap.md and the multilingual roadmap summary in sequence, rather than directly deleting the main text of the current stage.

Action: At session closing, update the progress, next_steps, and cognitive fields of .session/current-task.yaml , and confirm that the task status of todo.md is consistent with the session protocol.