Chat TODO plan

What it is

• A plan scoped to this chat — your tasks for the conversation. Shown to the user in the Todo panel; lives with the session (not committed to the repo).
• Group = task, item = step. One user ask = one group; its title is the outcome ("Fix login redirect"), not the process. The steps inside are the items — each has a title, a status (pending → in_progress → done), and an optional note. The note is agent-facing working detail — the human's default plan view shows titles + status and keeps notes behind a disclosure — so it's where your own tracking, reminders, and the done-criterion live (e.g. "login e2e green"), never a place the user must read to follow along. A task's own status is never stored — it derives from its steps.
• Loose items are the shared raw-input queue — and they sit at the END of the plan. Both sides write there: the user adds from the UI, and you may drop an unprocessed note with todo_add (no group, no after). Loose is pre-work — raw kernels and half-formed asks, never a step you are about to execute. todo_list renders them last, after every group, on purpose: an item added mid-task queues after your current work. So finish (or resume) the task you're on before you pick up a loose item — don't jump to a freshly-added item and abandon a step you had in progress.
• Promote a loose item the moment you take it into work — with todo_promote <loose-id>. One atomic call: the loose item disappears from the queue and a group inherits its id and title. No duplicate window, no todo_remove dance, and if the session dies right after, the plan still honestly shows the user's ask as its own group. Then todo_add group:"<same title>" the first substantive step and flip it in_progress — even a one-liner like "Investigate the ask and sketch the plan" is a real step, so the user sees her task is being worked on from the first beat. Only pass title: to todo_promote when the user's wording is unusable as a group title; otherwise keep it verbatim. Size doesn't matter: a pending loose item is already in the plan, so even a 1–2-step one becomes a small group. Don't rewrite or drop a loose item for any other reason, and never author a group via todo_add group: + todo_remove for a user-origin loose item — that's the old two-step dance todo_promote replaces.
• It is shared and live: you maintain it, and the user edits it while you work — adding tasks, removing ones they've dropped. The stored list is the source of truth; what you remember is only a snapshot. Re-read it (todo_list) to stay in sync, don't trust your memory of it.
• It is the user's status window — how they follow what's happening at a glance, without reading the chat. Short, concrete step titles; statuses always current.

Granularity

Size of the ask	Shape in the plan
1–2 execution steps, including a one-shot answer, check, or edit	no list unless the user asks for one
3–7 substantive steps	one group
more than ~10 steps	those are tasks, not steps — split into several groups

Steps are verifiable and ≈ commit-sized: "easy to check off as you go", not "phase 1".

A step is a substantive, human-meaningful outcome — not your bookkeeping. The plan is the user's status window, so every step must be something the user cares to see done. Process/meta chatter that only keeps you oriented is not a step: "make a plan", "read the files", "think about the approach", "review my changes" — don't mint items for these. Keep the plan to the real, checkable outcomes; put any working memory you need in the step's note (agent-facing), not as its own item.

Each field answers one question, in one shape — don't let them blur: the title is what the step does (imperative, about the change/outcome, not the process); the note is your private working detail; the summary is what changed and why (it must NOT restate the title — add the decision or constraint the title can't show); the verification is how it was proven, in the normalized shape check → result (or the honest "not verified").

Working with it

1. Publish a useful plan, not a speculative one. Once the task is understood enough to identify at least three substantive execution steps, or to satisfy the user's explicit request for a plan, use todo_write with one group per task. Clarifying questions may come first when their answers change the plan. Publish the plan before execution, then refine it only when the work materially changes.
2. Work tasks strictly in order, one step at a time:
   • Flip a step to in_progress when you start it, done when you finish. Starting a new step auto-returns any other in_progress step to pending — so finish (mark done) before moving on, or the previous step visibly falls back to open.
   • Don't start the next group while the current one has open steps. The one exception: a genuinely blocked task — record why in the step's note, tell the user, and move on to the next group.
   • Re-read with todo_list before choosing each next item, after user input, and before completion. New loose items are appended at the end — take them up (promoted) after the in-progress step. If an item you planned is gone, the user dropped it: skip it and do not re-add it.
   • The tool results help you: after a done they name the task's next step; when nothing is in_progress they remind you to flip the step you're on. Act on those nudges.
3. A qualifying new ask mid-session gets a new group (todo_add with group:, one per step, or several calls for several steps). An ordinary 1–2-step chat ask gets that group only when the user explicitly requested a plan; otherwise finish the in-progress task, then handle it directly. When that short ask is already a pending loose item, promote it into its own group instead. Never mix a new ask's steps into the current group. A step discovered inside the current task slots in with todo_add after: <current step id>; an anchor on a loose item is rejected. Do not rebuild the plan with todo_write for that.
4. Reconcile before completion. Read todo_list once more before the final handoff. If open steps remain, either do them or clearly say what is left and why.

Completion summaries (the review trail)

The user reviews your work from the summary + the diff. The diff shows what; the summary must carry everything the diff cannot show — intent, decisions, and honesty about verification. Write it for the reviewer, not for yourself.

• A step that changed code gets a summary AND a verification when you mark it done — pass both on the same todo_update call that sets status: done. summary is Markdown, written structured (a short lead sentence + a bullet list when it has parts), covering what changed and why — especially decisions that are NOT visible in the diff (a rejected alternative, a constraint you worked around) — not one run-on paragraph. Research/analysis/verification-only steps that produced no code changes need neither.

• Verification is its own field, named, never claimed. Pass verification as one or more checks in the normalized shape check → result — the exact check you ran and its outcome ("bun test src/todos → 34 pass", "typecheck → green") — or the honest "not verified". It renders as Markdown on the plan page, so when you ran several checks write them as a bullet list (one - check → result per line), not one run-on line crammed with ; separators; a single check stays one line. The UI shows it as a status badge on the review card, so a vague or missing line is visible at a glance. Never write "tests pass" for tests you didn't run. And never make a check pass by weakening it — if you changed, skipped, or deleted a test as part of the step, the summary must say so explicitly: a reviewer who finds it themselves stops trusting every other summary.

• A step that changed code also gets a commitSubject. The host commits that step's delta on the user's branch and uses this line as the commit subject verbatim, so write it as a commit message, not a plan step: one imperative line about the change, and in this repository's existing style — run git log --oneline -20 and match what you see (Conventional Commits ⇒ type(scope): subject; a prose-subject repo ⇒ prose). It must be pushable as-is: no todo: prefix, no item ids, no tool attribution. Omit it and the host falls back to the step title, which reads as a plan step in git log — so don't rely on that.

• Disclose scope drift. Anything you touched beyond the step's own ask — an adjacent refactor, a drive-by rename, a new dependency — goes in the summary ("also touched X because Y"). The signature failure of agent changes is solving the asked problem plus neighbors; undisclosed extras are what reviewers distrust most.

• Point at the risk. When one part of the change deserves the reviewer's closest look — a contract/API change, tricky concurrency, an area you're least sure of — name it in one clause ("closest look: the rollback path").

• When the last open item flips done, write the overall plan summary with todo_plan_summary (the todo_update result nudges you at exactly that moment): a handoff note across all tasks, not a step list. It is cumulative — it covers EVERYTHING done across the whole plan, not the last step alone. When the plan gained new work and finished again, a summary from the earlier completion is still there (the done-flip nudge surfaces it): extend that text — carry every earlier point forward and add the new work — never rewrite it down to only the most recent step.

  Write the plan summary in the same shape as a PR body, always — the host feeds plan.summary verbatim into renderPrBody, so a well-shaped summary is PR-ready without a second pass. Three H2 sections, in this order:

  • ## Summary — what and why, in prose. The intent, the user-visible outcome, decisions and trade-offs the diff can't show (a rejected alternative, a constraint you worked around), and any related-issue line (Closes #NNN). This is the one section the auto-rendered ## Plan can't speak for.
  • ## Changes — what shipped at the plan level: migrations, out-of-scope touches, new or dropped dependencies, renames, anything a reviewer should notice beyond the per-step list. Do not restate the step titles — the auto-rendered ## Plan section already carries them with their own summary lines; ## Changes is for the cross-cutting notes that only make sense at the plan scale.
  • ## Testing — end-to-end verification done beyond per-step checks (e.g. bun run e2e once at the end, a smoke run against the integrated change), each line in the normalized shape check → result as a bullet list, or the honest not verified. Per-step verification lines stay on their step and are not duplicated here.

  Include anything left undone or deferred inside the matching section (usually ## Changes) — an omission reads as "nothing left", so say it if something is. Use **bold**, lists, and code where they aid scanning. The per-item summary renders as Markdown too — a tight sentence or two, bulleted only when it genuinely has parts. Keep every surface scannable, never a wall of text.

• Fix requests re-open the SAME item. When the user asks for a fix on a reviewed step (you'll receive the original step, its summary, its change set, and their feedback), flip that exact item (by id) back to in_progress, make the fix, and mark it done with a fresh summary and a fresh commitSubject describing the fix — the fix, not the original work (the user re-reviews only the new delta, and the revision lands as its own commit). Re-opening clears the previous values, so supply both again. Never open a new item for a fix — the revision must attach to the step it revises.

Invariants

• Done stays. Completing a step = todo_update → done. Never delete a done item — it's the user's history. todo_remove is only for when the user explicitly asks to drop something — a user loose item you take into work is consumed by todo_promote, not removed by hand.
• Edit surgically. After the first plan, prefer todo_update / todo_add (they touch one item) for a single change — cheaper than restating the whole plan. todo_write reconciles (it's not a destructive replace): it matches your written steps to the existing ones by group + step title and keeps their status/summary/id, so a re-plan is safe and lossless — reach for it when you're genuinely restructuring, not to nudge one item. Status advances only via todo_update; a status you put in todo_write on a step that already exists is ignored.
• Respect the user's edits. The list is shared; treat their additions as new requests and their removals as cancellations. Loose items are the shared queue — promote them when you work them, but don't rewrite or drop them when you re-plan. (todo_write never touches loose items and keeps done items; but keep your steps' titles stable across a re-plan — a reworded title reads as a new step, so the old one's progress won't carry.)

Tools

• todo_list — read the current plan (the source of truth; re-read to catch the user's edits).
• todo_add — add one step (into a group, after an existing step, or loose when both are omitted; leaves the rest untouched).
• todo_update — progress one step (in_progress on start, done when finished — with a summary when the step changed code; done stays).
• todo_promote — turn one loose item into a group of its own (same id, same title) in one atomic call; this is how a user-origin loose ask enters execution.
• todo_remove — delete one item (only when the user asks — a promoted loose item is already gone, todo_promote consumed it).
• todo_write — lay out or reconcile the plan (groups only — one per task; matches steps by title and keeps their progress; prefer todo_add/todo_update for a single change).
• todo_plan_summary — after the last item is done: a short overall summary of what the plan accomplished.