Skip to content

The plan-todo loop

Statefulness is compaction made durable. The sprint mandate lives in two files, not in any agent's head — agents get compacted, files don't.

The loop

  1. Receive the big ask. A huge list of instructions, a pivot, a brain-dump. It MUST include (or you must extract) explicit testing criteria — what "verified" means for each chunk. If criteria are missing, derive them from the repo's test suite and say so; don't ask.
  2. Write the unordered TODO (TODO.md at repo root). Every item goes in — scope capture, nothing lost. No ordering, no priority anxiety. Include the verification criteria with each item where they're known.
  3. Write the ordered PLAN (PLAN.md at repo root). Numbered phases, numbered items inside phases. Each item: do it, verify it, mark it done, move on. Put the build command at the top. If phases execute out of numeric order, say so at the top ("Current trajectory: 10 → 11 → 12 → 9.6–9.8").

  4. Put the mandate at the top of BOTH files, verbatim:

    ## DO NOT ASK USER FOR FEEDBACK — THIS IS THE USER FEEDBACK. ## DO NOT ASK USER FOR NEXT STEPS — THESE ARE THE NEXT STEPS.

Any future agent — compacted, delegated, or fresh — reads the files first and inherits the mandate without needing the conversation that produced it. 5. Work the PLAN, top uncompleted item first. When you finish an item: - Verify it against its stated criteria (build, test, live eyeball — whatever the item says). No criteria were written? The repo's test suite is the floor. - Do NOT stop to seek feedback. - Mark it done in BOTH TODO.md and PLAN.md (with a one-line evidence note: date + what verified it). - Proceed to the next PLAN item. - Continue until everything in TODO and PLAN is complete. 6. Done means done. Only when every item is checked (or explicitly deferred with a reason written in TODO) do you report completion and ask what's next.

Rules that keep the loop honest

  • Scope discovered mid-work goes into TODO.md IMMEDIATELY. Never hold it in head — context gets compacted and the next agent only has the files.
  • Blocked ≠ stopped. If an item is genuinely blocked (missing credential, destructive/irreversible action, real intent ambiguity), don't stall and don't guess: write the blocker into TODO/PLAN with the reason, skip to the next unblocked item, surface it in the end-of-sprint summary. Facts are for search; only genuine intent is ever asked — and a sprint almost never needs it.
  • Uncommitted = unfinished. Commit at each natural checkpoint (one item or one coherent unit). A working tree full of never-compiled edits blocks everyone.
  • Edit the plan files in place. One TODO.md, one PLAN.md, one truth. Never -v2. Re-read before editing; never edit from memory.
  • Evidence over vibes. "Marked done" requires the thing actually ran: the build passed, the tests passed, the command was eyeballed. Write what verified it.
  • The user's rapid direction changes ARE the feedback. When they interject, fold it into TODO/PLAN on the spot and keep moving — don't restart the loop.

Picking up someone else's sprint (compacted/next agent)

  1. Read TODO.md and PLAN.md top to bottom — the mandate headers apply to you.
  2. git status + git log --oneline -5: find uncommitted work. Uncommitted edits are the most likely place the last agent died — finish them FIRST (they may never have compiled).
  3. Find the first unchecked PLAN item in the stated trajectory. Do it. Verify it. Mark it. Move on.