---
name: todos
description: "Use when the user asks for a shared plan, a task needs at least three substantive execution steps, or a loose TODO is pending. Without an explicit plan request, not for one-shot answers or checks, or one- to two-step work that is not already in the list."
---

# 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 when you take it into work** — never progress the raw text in place. Author a
  group with an outcome title and its decomposed steps (`todo_add` with `group:`, one call per step),
  flip its first step to `in_progress`, then `todo_remove` the raw loose item. 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.
- 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.** Include what was verified
   end-to-end and anything left undone or deferred — an omission here reads as "nothing left", so say it
   if something is. **The plan view renders this as Markdown, so
   write it structured, not one dense paragraph:** a lead sentence, then a short bulleted breakdown (e.g.
   what shipped / what was verified / what's left), using `**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 both 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, or for
  the raw loose item you just promoted into a group.
- **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_remove` — delete one item (only when the user asks, or the raw loose item you just promoted).
- `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.