Todo Continuation

Relevant source files

The following files were used as context for generating this wiki page:

• packages/harness/src/todo-continuation.ts
• packages/cea/src/tools/planning/todo-write.ts
• packages/cea/src/middleware/todo-continuation.ts
• packages/cea/src/tools/planning/todo-write.test.ts
• packages/harness/src/todo-continuation.test.ts
• AGENTS.md

The Todo Continuation system is a specialized module within the plugsuits repository designed to manage, track, and automatically resume complex tasks through structured todo lists. It serves as a persistence and reminder layer that ensures an agent can maintain progress across multiple turns of interaction, particularly for tasks involving more than three distinct steps or complex refactoring requirements.

This system is divided into a model-agnostic core located in @ai-sdk-tool/harness and a concrete implementation within the Code Editing Agent (CEA) package. It allows the agent to read existing todo states, update task statuses, and receive system-level reminders to continue execution until all tasks are marked as completed.

Sources: packages/harness/src/todo-continuation.ts, packages/cea/src/tools/planning/todo-write.txt, AGENTS.md:38

System Architecture

The architecture relies on a shared SessionManager to isolate todo lists by session ID and a filesystem-based persistence layer.

Core Components

1. TodoContinuation (Harness): The base class providing logic to retrieve incomplete tasks from JSON files and generate prompt templates.
2. todo_write (Tool): A callable tool that allows the agent to update its task list, persisting changes to both JSON (for machine reading) and Markdown (for human/agent inspection).
3. CEA Middleware: A layer that configures the harness logic with specific prompt templates that enforce "Continuous Execution" rules.

Sources: packages/harness/src/todo-continuation.ts:74, packages/cea/src/tools/planning/todo-write.ts:133, packages/cea/src/middleware/todo-continuation.ts:77

Data Flow

The following diagram illustrates the flow from task creation to autonomous continuation.

Data Structures

TodoItem Schema

The system uses a strictly typed TodoItem structure to track the lifecycle of a task.

Field	Type	Description
id	string	Unique identifier for the task.
content	string	Brief description of the task (required).
status	enum	One of: pending, in_progress, completed, cancelled.
priority	enum	One of: high, medium, low.
description	string	(Optional) Detailed task context.

Sources: packages/harness/src/todo-continuation.ts:5-11, packages/cea/src/tools/planning/todo-write.ts:25-36

Persistence Format

Todo data is stored in the system's temporary directory (TODO_DIR) using the format ${sessionId}.json.

{
  "todos": [
    {
      "id": "1",
      "content": "Implement auth",
      "status": "in_progress",
      "priority": "high"
    }
  ],
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "sessionId": "uuid-v4-string"
}

Sources: packages/cea/src/tools/planning/todo-write.ts:145-155, packages/cea/src/tools/planning/todo-write.test.ts:88-91

Execution Logic

Continuous Execution Rules

When the TodoContinuation middleware is active, it injects a "CRITICAL EXECUTION" block into the system prompt. This enforces autonomy and prevents the agent from stopping prematurely.

• Autonomy: The agent must call tools (shell, file) directly rather than asking the user to run them.
• Sequential Processing: The agent should mark a task as in_progress, execute it, mark it as completed, and immediately move to the next.
• Stale Cleanup: Files older than 24 hours are automatically purged during todo_write execution to prevent context pollution.

Sources: packages/cea/src/middleware/todo-continuation.ts:25-56, packages/cea/src/tools/planning/todo-write.ts:100-120

Tool: todo_write

This tool is the primary interface for the agent to modify the todo state.

Configuration

Option	Type	Default	Description
todoDir	string	Required	Directory where todo files are stored.
promptTemplate	Function	defaultPromptTemplate	Fn that generates the internal system reminder.
userMessageTemplate	Function	defaultUserMessageTemplate	Fn that generates the user-facing reminder.

Sources: packages/harness/src/todo-continuation.ts:18-22

Summary

The Todo Continuation system provides the necessary infrastructure for autonomous, multi-step task execution. By combining structured JSON state, Markdown reporting, and aggressive system prompting, it ensures that agents remain focused on complex objectives and provide a clear audit trail of their progress within a specific session.