Todo List System

GetActiveTodoList Crash recovery gate

Before creating anything new, the agent checks whether an incomplete todo list already exists. This is the crash recovery mechanism: if the previous session was interrupted mid-task, the todo list is still in the database. The agent offers to resume it instead of starting fresh.

# Agent calls:
GetActiveTodoList()

# If an incomplete list exists:
Found incomplete todo list from previous session:
  Todo List #3 . "Migrate auth from SQLite to PostgreSQL"
  Status: in_progress
  Tasks: 2 completed, 3 pending

  Resume this todo list? [Y/n]:

If the user says yes, the agent skips steps 2-5 and goes straight to ExecuteNextTask. If no, the old list is cancelled and a new one is created.

CreateTodoList Allocate a new list

Creates a new todo list in the database and returns a todo_list_id. This ID is used by every subsequent call: AddTask, GetTodoList, ApproveTodoList, and ExecuteNextTask. The list is empty at this point .; no tasks yet.

# Agent calls:
CreateTodoList()

# Returns:
todo_list_id: 42

AddTask Populate the plan

Called once per task. Each task has five fields. The most important is context .; this is how you pass knowledge to the isolated subagent that will execute the task. Without it, the subagent has no idea what came before or what the broader goal is.

# Agent adds three tasks:
AddTask(todo_list_id=42, goal="Create a new database adapter for PostgreSQL",
         requirements="Must match the existing SQLite adapter interface",
         context="The project uses src/db/adapter.py as the base class...",
         order_index=0)

AddTask(todo_list_id=42, goal="Update all callers to use the new adapter",
         context="Callers found in src/api/routes.py, src/auth/login.py...",
         order_index=1)

AddTask(todo_list_id=42, goal="Run tests and fix any regressions",
         notes="Use pytest. The test suite is in tests/",
         order_index=2)

GetTodoList Review the plan

Retrieves the complete todo list with all tasks and their statuses. The agent uses this to verify the plan looks correct before asking for approval. All tasks start as pending.

# Agent calls:
GetTodoList(todo_list_id=42)

# Returns:
Todo List #42 . 3 tasks
──────────────────────────────────────────────
[0] pending  Create a new database adapter for PostgreSQL
[1] pending  Update all callers to use the new adapter
[2] pending  Run tests and fix any regressions

ApproveTodoList User approval gate

Displays the full plan to you and asks for approval. This is the human-in-the-loop checkpoint. No code has been touched yet. If you approve, the todo list status is set to approved and tasks can be executed. If you reject, the agent rebuilds the plan based on your feedback.

# Agent calls:
ApproveTodoList(todo_list_id=42)

# User sees:
Todo List #42 . 3 tasks
──────────────────────────────────────────────
[0] Create a new database adapter for PostgreSQL
[1] Update all callers to use the new adapter
[2] Run tests and fix any regressions
──────────────────────────────────────────────

Approve this plan? (y/n):

If you approve, the plan proceeds to execution. If you reject, the todo list status becomes rejected and the agent must rebuild the plan incorporating your feedback.

ExecuteNextTask Sequential execution loop

Each call dispatches the next pending task to a subagent. The subagent is an isolated session .; it has no access to the orchestrator's conversation history. It receives the task's goal, requirements, notes, context, and a summary of all previously completed tasks.

The agent calls ExecuteNextTask repeatedly until all tasks are done. Each call dispatches exactly one task. Tasks always execute in order_index order .; never in parallel.

# Agent calls sequentially:
ExecuteNextTask(todo_list_id=42)  # dispatches task [0]
ExecuteNextTask(todo_list_id=42)  # dispatches task [1]
ExecuteNextTask(todo_list_id=42)  # dispatches task [2]

# After the last task completes:
All tasks completed. Todo List #42 has been automatically deleted.