EN Course 09 Plan and Todo Workflow

Plan and Todo Workflow

bash-agent separates long-lived plans from short-lived progress tracking.

There are three concepts:

Concept	File / Tool	Purpose
draft plan	PLAN_DRAFT_FILE	editable planning text that does not enter the prompt
locked plan	PLAN_FILE	confirmed plan included in the system prompt
todo checklist	TodoWrite	current execution progress

Why Draft Plans Exist

Writing to PLAN_FILE changes the system prompt. If every planning revision entered PLAN_FILE, each revision would invalidate the prompt cache.

So planning uses PLAN_DRAFT_FILE first. Only an explicit confirmation moves the draft into PLAN_FILE:

store_plan_confirm() {
    [[ -n "$PLAN_DRAFT_FILE" && -s "$PLAN_DRAFT_FILE" ]] && {
        mv "$PLAN_DRAFT_FILE" "$PLAN_FILE"
        : > "$PLAN_DRAFT_FILE"
        return 0
    }
    return 1
}

PlanConfirm

PlanConfirm is a deliberate cache boundary. The Bash tool implementation compacts before moving the draft:

tool_plan_confirm() {
    if store_plan_draft_has; then
        agent_compact_context plan_confirm
        store_plan_confirm
        printf 'Plan confirmed and locked in.'
    else
        printf 'Error: no plan draft found to confirm.'
    fi
}

The ordering matters:

draft edits -> confirm -> compact -> locked plan -> execute

Lifecycle States

A practical lifecycle view:

idle -> drafting -> revised -> confirmed -> executing -> cleared

Transitions:

• REVISE: keep editing PLAN_DRAFT_FILE
• CONFIRM: lock draft into PLAN_FILE through PlanConfirm
• CANCEL: clear draft and return to idle
• PlanClear: remove locked plan after execution completes

Common Failure Pattern

Wrong order (causes protocol drift):

edit draft -> start execution directly -> later confirm

Correct order:

edit draft -> confirm -> execute with todo tracking -> clear

Keeping this order prevents stale draft text from diverging from the active runtime plan.

TodoWrite

TodoWrite tracks progress inside the current task. It is not the durable plan. The system prompt guidance tells the model to use it for complex multi-step work, keep one active item, and update it as work completes.

This split keeps planning, execution tracking, and prompt cache behavior separate.

Next

Sub-Agent Runtime explains how a child agent reuses the same runtime layers while reporting back asynchronously.