Skip to content

TaskTrack.md

Latest commit

 

History

History
297 lines (184 loc) · 17.9 KB

TaskTrack.md

File metadata and controls

297 lines (184 loc) · 17.9 KB
Raw

The TaskTrack Specification v1_draft_now

Overview

TaskTrack is a standard for managing structured work plans executed by AI agents. It defines text-based file formats, a folder layout, and usage rules that enable an AI agent to

  • author a structured plan of tasks from requirement documents,
  • read a plan to select the next task to work on,
  • update a task with results and mark it done or failed,
  • mark a task as waiting for human feedback.

Plans are stored as plain markdown files, requiring no tooling beyond file read/write access.

Conformance

This specification follows The Specify Standard v1_draft_20260522T164000Z.

The filename of a publication of this specification is TaskTrack-[REVISION_IDENTIFIER].md.

All file formats defined in this specification conform to MiniMark Specification 2026-03-31.

All timestamps use ISO 8601 format in UTC.

Specification

Building Blocks

Plan

A plan is a non-empty collection of tasks which are grouped into phases. A plan has at least one phase and every task belongs to exactly one phase.

A plan has a title and an identifying code consisting of 3 to 5 uppercase letters A through Z (no digits, no whitespace, no special symbols).

A plan resides in a folder (called the plan folder) and consists of exactly one overview file and exactly one task file for every task in the plan. Furthermore the plan folder must also contain a publication of this specification. The plan folder's name is irrelevant and ignored as far as this specification is concerned. There are no rules regarding the plan folder's location in the file system as long as the path is known and the folder is accessible.

Phase

A phase is a grouping of tasks with respect to task processing sequence.

The list of phases in a plan is ordered and 1-based. A phase has a title and is identified by its ordinal number. Tasks in higher-numbered phases are only allowed to get processed when all tasks in lower-numbered phases are done.

Phases exist to minimize the number of explicit dependencies between tasks. In an ideal plan, all tasks are dependency-free because all ordering constraints are expressed implicitly through phase assignment.

Task

A task is the atomic unit of work to be processed by an AI agent. A task represents a logically self-contained piece of work — such as implementing one feature, preparing one document, or creating one image — that can be completed within a single agent run.

Every task in a plan has a title and a unique task identifier of the form [PLAN_CODE]-[COUNTER] where [COUNTER] is a non-zero natural number. All task identifiers of a plan must have mutually distinct counters. This numbering should consist of consecutive numbers.

A plan's task identifiers have a total order with respect to their counters, such that id FOO-2 is lower than id FOO-10.

A task has a status (also called the task status) whose valid values are four-letter uppercase codes:

  • OPEN — not yet selected for processing by an agent.
  • BUSY — an agent has selected and is actively processing this task.
  • WAIT — an agent has stopped processing this task because human feedback is required to further process it.
  • DONE — the task has been completed successfully.
  • FAIL — the task could not be completed.

NOTE: In prose, the terms open, busy, waiting, done, and failed refer to tasks with the respective status code.

A task may declare dependencies on other tasks, but these tasks must belong to the same phase as the task itself. Since phases are already executed in sequence, it is forbidden to include dependencies on tasks in earlier phases (redundancy) or to include dependencies on tasks in later phases (contradiction).

A task is called eligible for processing if

  1. it is open,
  2. either
    • it is in phase 1,
    • it is in a higher-numbered phase such that all tasks in all preceding phases are already done,
  3. all tasks it depends on are already done.

It follows that if a task fails, then all tasks in subsequent (higher-numbered) phases can never execute because the second condition cannot be met anymore. Task failure is considered a rare incident which renders plan completion impossible.

File Contents

Overview File

The filename for the overview file is [PLAN_CODE]-TaskTrack.md.

The overview file is a MiniMark document with the following structure:

  • A header section:
    • Plan code and title.
    • A comprehensive description of the overall goal behind this plan to give context and background information to AI agents.
    • Creation timestamp in UTC. Must not be updated or changed ever.
    • A comma-separated list of absolute file paths to documents containing relevant information for AI agents to take into account for processing tasks, or none if there are no such documents.
  • A heading for every phase in ascending order (phase 1 first).
  • A status entry for every task in this phase.
    • The tasks should be sorted in ascending order of their ids.
    • The entry shows the task's status (four-letter code) in brackets.
    • The agent processing this task must update the status code when the task's status changes.
# [PLAN_CODE] - [PLAN_TITLE]

**Objective**: [OVERALL_PLAN_OBJECTIVE_DESCRIPTION]

**Created**: [TIMESTAMP_ISO_8601_UTC]

**Resources**: [COMMA_SEPARATED_LIST_OF_ABSOLUTE_FILE_PATHS_OR_NONE]

## [PHASE_NUMBER]: [PHASE_TITLE]

* [OPEN] [TASK_ID]: [TASK_TITLE]

Task File

The filename for a task file is [TASK_ID].md.

A task file is a MiniMark document with the following structure:

  • Task identifier and title as heading.
  • Task status (four-letter code). Must be updated by the processing agent according to the rules defined in this specification.
  • Last updated timestamp. Must be set by the processing agent with the current time in UTC whenever a change is applied to the file.
  • A comma-separated list of task ids which must be done before processing of this task can start, or none if the task has no dependencies.
  • A comprehensive description defining what processing this task is about. Avoid mentioning too many details here. Instead, reference resources listed in the overview file header for additional information like requirements, designs, standards etc.
  • A bullet point list of acceptance criteria for this task's status to be set to done.
  • When waiting: a Request field with a detailed description of what exactly a human is expected to do. The agent generates a new request each time human feedback is required. New requests are placed below existing request/response pairs. Existing requests and responses are never deleted.
  • A Response written by a human to the above request in case this task had been flagged for human feedback (status WAIT). This field is never created or altered by agents.
  • When done: a Resolution field with a brief description of how the task was completed. This field is only present for tasks with status DONE.
  • When failed: a Failure field with a brief description of why the task failed. This field is only present for tasks with status FAIL.
# [TASK_ID]: [TASK_TITLE]

**Status**: [TASK_STATUS]

**Updated**: [TIMESTAMP_ISO_8601_UTC]

**Dependencies**: [COMMA_SEPARATED_LIST_OF_TASK_IDS_OR_NONE]

**Description**: [TASK_DESCRIPTION]

**Acceptance**: [BULLET_POINT_LIST_OF_CRITERIA]

**Request**: [FIRST_REQUEST_FOR_HUMAN_FEEDBACK]

**Response**: [HUMAN_FEEDBACK_TO_THE_FIRST_REQUEST]

**Request**: [SECOND_REQUEST_FOR_HUMAN_FEEDBACK]

**Response**: [HUMAN_FEEDBACK_TO_THE_SECOND_REQUEST]

**Resolution**: [DESCRIPTION_WHEN_DONE]

**Failure**: [DESCRIPTION_WHEN_FAILED]

NOTE: Request/Response pairs and Resolution/Failure are shown together for reference. In practice, a task file contains zero or more Request/Response pairs, plus exactly one of Resolution or Failure (when DONE or FAIL, respectively), or neither (when OPEN, BUSY, or WAIT).

Procedures

This specification defines the following two procedures. A step-by-step description of each procedure is given in subsequent sections.

Plan Authoring

An AI agent authors a plan from one or more requirement documents provided by the user during a plan authoring run. The authoring process produces one overview file and one task file per task, all placed in a single folder.

This specification expects that the authoring of a plan is achieved with a single agent run and does not provide a recovery mechanism for resuming an aborted plan authoring.

The step-by-step description for the procedure is given in section "Procedure: Plan Authoring Run".

Plan Execution

A plan execution run either starts or continues to process and complete open tasks from an existing, previously authored, plan. Its main objectives are task selection and the launch of a task processing run sub-procedure. It is structured as a loop which continues until no more tasks can be selected for processing.

At any time at most one task processing run is executing under the control of a plan execution run.

This procedure has the exclusive permission to modify the overview file. It is allowed to read task files but must not modify any task files under any circumstances.

The step-by-step description for the procedure is given in section "Procedure: Plan Execution Run".

Note: All task processing is governed by the TaskTrack specification version used for plan authoring and placed inside the plan folder. This specification does not support migrations of TaskTrack specification versions for existing TaskTrack plans.

Task Processing

A task processing run encompasses the execution of all required activities to complete exactly one open task.

This procedure has the exclusive permission to modify the task file of the task it is processing. It must not either read or modify any other task files under any circumstances. It is allowed to read the overview file but must not modify it under any circumstances.

The step-by-step description for the procedure is given in section "Procedure: Task Processing Run".

Procedure: Plan Authoring Run

The authoring agent is provided with

  • a publication of this specification,
  • a file path to a directory serving as the plan folder,
  • one or more requirement documents (and possibly additional information) as the basis for the plan.

The authoring agent must:

  1. Read and analyze all provided requirement documents.
  2. Choose a plan code (3 to 5 uppercase letters) and a descriptive plan title.
  3. Decompose the work into tasks. Each task must be a logically self-contained piece of work completable within a single agent run. Keep track of inter-task dependencies.
  4. Assign tasks to phases. Group tasks into phases such that dependencies between tasks in one phase are minimized. Tasks that depend on the output of other tasks should be placed in a later phase rather than in the same phase with an explicit dependency. Explicit intra-phase dependencies should only be used when phase separation would be impractical. Double check that no inter-phase explicit dependencies exist as they are not allowed.
  5. Within each phase, assign task identifiers with counters unique across the entire plan.
  6. Write the overview file with the plan code, title, objective, creation timestamp, and absolute file paths to the source requirement documents as resources.
  7. Write one task file per task with status OPEN, creation timestamp, no resolution or failure field, a description, and acceptance criteria derived from the requirements.
  8. Make sure that a publication of this specification is contained in the plan folder.

The authoring agent must not process any tasks. Authoring and processing are separate operations.

Procedure: Plan Execution Run

This procedure requires as input the location of the plan folder.

Step 0: Recovery

Output the following step message: TaskTrack STEP: Recovery.

Consider the possibility that the previous plan execution run exited in an uncontrolled way due to an agent crash.

  1. Check if the overview file contains a task with status BUSY (there can be at most one such task).
  2. If this is the case then read the relevant task file and set the task status in the overview file to the same status as in the task file.
  3. If the task status is still BUSY then the agent must decide from the task description if the task can be resumed or must be failed. If the task can be resumed then proceed to section "Step 3: Execute" with this task as the selected task. Otherwise proceed to section "Step 4: Complete" and fail the task.
  4. In all other cases continue with section "Step 1: Screen".

Step 1: Screen

Output the following step message: TaskTrack STEP: Screen.

Read the overview file to find open tasks eligible for processing. First, identify the current active phase (the lowest-numbered phase containing open, busy, or waiting tasks, provided all tasks in all preceding phases are done). Secondly, identify all open tasks in the current active phase where all declared dependencies are already done.

Step 2: Select

In case the list of eligible tasks is non-empty, select the task with the lowest id from the list of eligible tasks and set this task's status in the overview file to BUSY.

Output the following step message: TaskTrack STEP: Select Task [TASK_ID].

In case the list of eligible tasks is empty, finish the plan execution run and output the following exit message (evaluate conditions in the order listed):

  • TaskTrack EXIT: Plan Completed in case every task in the plan is done,
  • TaskTrack EXIT: Failed Tasks in case there exist failed tasks in the plan,
  • TaskTrack EXIT: Waiting for Human Feedback in case there are no failed tasks but there are waiting tasks in the plan,
  • TaskTrack EXIT: No Eligible Tasks otherwise.

Step 3: Execute

Launch a task processing run procedure and pass the location of the plan folder and the task identifier of the selected task to it so that it is capable of reading and modifying this task file, reading the overview file, and reading the publication of this specification.

Step 4: Complete

When the task processing run launched in the previous step has completed and returned the new task status:

  • If the task is done, set the task's status code to DONE in the overview file.
  • If the task is waiting, set the task's status code to WAIT in the overview file.
  • If the task has failed, set the task's status code to FAIL in the overview file.

Output the following step message: TaskTrack STEP: Complete.

Proceed to section "Step 1: Screen".

Procedure: Task Processing Run

This procedure requires as input the location of the plan folder and a task identifier.

Step 1: Claim

Output the following step message: TaskTrack STEP: Claim.

Set the selected task's status to BUSY and update the timestamp in the task file. This must happen before any other work begins.

Step 2: Execute

Output the following step message: TaskTrack STEP: Execute.

Carry out the work described in the task's description, consulting any resources listed in the overview file header. Take human feedback into account if it had been requested and received. Adhere to the acceptance criteria.

Step 3: Conclude

Output the following step message: TaskTrack STEP: Conclude.

  • If all acceptance criteria are met, set the task status to DONE, add a Resolution field describing what actions have been taken, and update the timestamp in the task file.
  • If human feedback is required (possibly again) to continue processing the task, set the task status to WAIT, add a new Request field describing exactly what a human is expected to do (information to be provided, actions to be taken etc.), and update the timestamp in the task file.
  • If the task cannot be completed, set the task status to FAIL, add a Failure field describing why, and update the timestamp in the task file.

Step 4: Finish

Output the following step message: TaskTrack FINISHED: Task [TASK_ID].

This finishes the task processing run. Hand back control to the plan execution run which launched this task processing run and return the new task status as the result of this task processing run.

Do NOT take any further actions. Do NOT work on any other tasks. Do NOT jump back to a previous procedure step.

Human Feedback

When a plan execution run terminates with the TaskTrack EXIT: Waiting for Human Feedback exit message then at least one task requires human attention before another plan execution run can achieve progress.

Humans must give feedback only between plan execution runs, never during an executing plan execution run.

The manual human feedback workflow is as follows:

  1. Open the overview file and identify all tasks in status WAIT. For either all or selected waiting tasks:
    1. Open the respective task file.
    2. Read the latest Request field entry created by an agent.
    3. Create a Response field directly below the latest Request field and provide feedback.
    4. Set the task status to OPEN.
    5. Save and close the task file.
    6. In the overview file set the status of the respective task to OPEN.
  2. Save and close the overview file.
  3. Start a new plan execution run.

© 2026 New Adventures in IT and TaskTrack contributors. Licensed under CC BY 4.0.