Long-running work

Four mechanisms, four different lifespans. Using the wrong one is how work gets lost between turns or how a five minute task gets wrapped in ceremony.

Mechanism	Lives for	Use when
todo	the current mission	a task has several steps you must not drop
plan_mode	until approval	the change is large enough that the user must agree first
kanban	across sessions	the user tracks work items over days
mission	across sessions, repeatedly	an objective needs many iterations, possibly on a schedule

None of these is the right answer when a CONDITION decides rather than you. "Warn me when X happens", "if Y is true, do Z": that is a watcher, see watcher-design, and its rules cost nothing while nothing happens. A mission on a schedule that keeps checking whether something occurred is the expensive way to write a watcher.

Todo

todo takes action, plus text to add and id to target an existing entry.

Use it as soon as a request has more than about three steps. Its job is not decoration: it is what stops step four being forgotten after a long tool result pushes it out of view.

• Add each step as its own entry, phrased as an action.
• Mark one in progress, do it, mark it done, then move on. One in progress at a time.
• If you discover a new step mid-task, add it immediately rather than holding it.

A todo list that is written once and never updated is worse than none: it reports progress that did not happen.

Plan mode

plan_mode with titre creates plan.md in the session's working directory, holding a skeleton with three headings: Context, Proposed Steps, Approval Required. You then fill it in BEFORE changing anything.

Use it when the change is structural: many files, a migration, a deletion, anything the user would want to veto. Do not use it for a fix you were explicitly asked to make.

1. plan_mode with a short descriptive titre. The answer names the absolute path it wrote; read that path rather than assuming where it landed.
2. Fill in plan.md with file_write or file_edit: what you will change, in what order, what could break, what you will verify. Concrete file paths, not intentions. For what a good plan document contains, open the plan skill.
3. Present it and wait for approval. Do not start while asking.

An existing plan.md is moved aside, not overwritten. If one is already there it is renamed plan-<date>_<time>.md and the answer names the new path. Nothing is lost, but the old plan is no longer where you left it: if you meant to continue it rather than start a fresh one, open it at the path the answer gives instead of calling plan_mode again.

Kanban

The board is global and persists across sessions. It belongs to the user, not to a mission.

• kanban_list takes no arguments and shows every task with its status and its UUID. Read it before adding, to avoid twins, and to get the id you will need next.
• kanban_create with title and optional description adds one. It answers with the new task's UUID.
• kanban_next takes NO arguments. It does not advance anything: it ANSWERS the question "what should I do next", returning the first Ready task, or a task whose dependencies are all completed. When nothing is actionable it says so.
• kanban_complete with id and result closes a task. Completing a task automatically unblocks the tasks that depended on it, which is what makes kanban_next useful on the following call.

id is the UUID printed by kanban_list or kanban_create. It is validated: a title, a position or a truncated id is rejected outright.

result is required by kanban_complete and is not a formality: it is what the user reads later to know what actually happened. "Done" is useless. Say what changed and how it was verified.

The normal loop is therefore kanban_next, do the work, kanban_complete with that task's id, kanban_next again.

Missions

A mission is an objective pursued across many iterations, optionally on a schedule.

• mission_list shows objective, cadence, status, iteration count and last run.
• mission_create with objective, plus optional cadence as a cron expression (0 9 * * * for every day at 09:00) and optional channel for delivery. Omit cadence for a mission advanced manually.
• mission_delete removes one.

Write objective so it still makes sense with no conversation around it, and so that progress is recognisable. "Monitor the Rust ecosystem" never ends and never succeeds. "Every morning, report new releases of the crates listed in Cargo.toml, with breaking changes flagged" can be executed and judged.

Check mission_list before creating: a duplicate mission means the work runs twice and the user is notified twice.

Finishing

task_complete with summary and confidence ends the mission. Call it ONLY when the work is finished and verified.

• summary states what was accomplished, concretely.
• confidence must be honest. Lowering it when something is unverified is the correct behaviour, not a weakness.
• artifacts lists what was produced, when there is anything.

Do not call it for an intermediate step. Do not call it while something is still failing: report the failure instead. A completion claimed on broken work is the worst possible outcome, because it stops anyone from looking.

Traps

• Kanban is not todo. Kanban outlives the session and is the user's board. Todo is scratch space for the current mission. Filling the user's board with your internal steps is noise they have to clean up.
• kanban_next does not advance a task. It reads. Calling it in a loop without calling kanban_complete returns the same task forever.
• kanban_complete requires result, and id must be the UUID. A call with the title instead of the id is rejected.
• A mission with a cadence runs on its own. Creating one is a standing commitment, not a one-off request. Confirm the cadence with the user before creating it.
• Plan mode is not a way to avoid deciding. If the user asked for a specific change, make it.

Failure modes

Steps get forgotten in long tasks. No todo list, or one never updated. Add the remaining steps now and mark honestly what is actually done.

The same mission fires twice a day. Two missions with near-identical objectives. mission_list, then mission_delete the duplicate.

A kanban task sits in progress forever. It was advanced but never completed, or the work stopped. Close it with a result that says what happened, including "abandoned because X". An honest closure is information; an open card is not.