Add a Plan/Todo System to Your Agent

The route

4 steps to Done

1. 01

   Design the todo data model and tool

   Structured plans beat prose plans because the harness can enforce them.

   Preview prompt + verify gate ▾ Hide ▴

   Design a todo subsystem for the agent. Data model: a list of items, each with id, content (imperative phrase), and status (pending | in_progress | completed). Tool interface: todo_write(items) replaces the full list (simplest correct design - the model always sends the complete list). Harness rules to implement: reject lists with more than one in_progress item; reject status regressions from completed to pending without an explanatory note field; store the list in loop state, not in the message history. Write the tool schema and the validation rules first.

   • ✓ Full-list-replace semantics chosen and documented
   • ✓ One in_progress enforced by validation
   • ✓ State lives in the harness, not chat history
2. 02

   Render the plan into context every turn

   A plan the model cannot see is a plan it will not follow.

   Preview prompt + verify gate ▾ Hide ▴

   Implement plan rendering: every turn, after tool results are folded in, append a synthetic system-style reminder block containing the current todo list rendered compactly (id, status marker, content), the current in_progress item highlighted, and counts (done/total). Keep it under 15 lines. This block is regenerated each turn from harness state so it never goes stale. Verify by logging the exact context sent to the model and confirming the block reflects the latest state after each todo_write call.

   • ✓ Reminder block regenerated from state each turn
   • ✓ Block stays compact (under 15 lines)
   • ✓ Logged context confirms freshness
3. 03

   Enforce plan-first and completion gates

   The two gates that turn a todo list into reliability.

   Preview prompt + verify gate ▾ Hide ▴

   Add two harness gates. Gate 1 (plan-first): if the user task is non-trivial (heuristic: request mentions multiple actions, or the model's first response proposes multiple steps), require a todo_write call before any other tool executes - if the model tries to skip, return a corrective message. Gate 2 (completion): when the model signals finish, check todo state; if pending or in_progress items remain, block the finish and return the remaining items with an instruction to complete or explicitly cancel each with a reason. Test both gates with a multi-step task and verify the corrective messages appear in the transcript.

   • ✓ Plan-first gate blocks premature tool use
   • ✓ Completion gate blocks finishing with open items
   • ✓ Items can be cancelled with a recorded reason
4. 04

   Test the full planning lifecycle

   Prove the plan survives execution, failure, and resumption.

   Preview prompt + verify gate ▾ Hide ▴

   Run three lifecycle tests. Test A (happy path): a 5-step task - verify plan created first, items move pending -> in_progress -> completed one at a time, finish allowed only at 5/5. Test B (failure mid-plan): make step 3 fail - verify the item stays in_progress or gains a new corrective item rather than being falsely completed. Test C (resume): stop the loop after step 2, restart with persisted state - verify the plan and current item restore and execution continues from step 3. Record all three transcripts and write a 5-line summary of what the todo system caught that the bare agent would have fumbled.

   • ✓ Happy path executes items in order
   • ✓ Failed step is never marked completed
   • ✓ Resume continues from the correct item

Research-backed

Sources behind this flow