Task files

Task files are one-shot Markdown work items for one agent. The frontmatter stores task metadata. The body stores the work instruction sent to the agent when the task is claimed.

Location

Active and paused tasks live under the agent home:

${TOOLANG_ROOT}/agents/<agent>/tasks/<id>.md

Archived tasks move under an hourly UTC archive bucket:

${TOOLANG_ROOT}/agents/<agent>/archive/tasks/<YYYYMMDDTHHZ>/<id>.md

Authored files can use a readable filename such as review-docs.md. If the file is missing id, Toolang writes one when it scans the task.

Markdown format

A minimal task can be only frontmatter plus a Markdown body:

---
title: Review API changes
---
 
Review the API changes and summarize risks.

The explicit form is:

---
id: 3nprht9x
title: Review API changes
state: active
stage: todo
---
 
Review the API changes and summarize risks.

state: active and stage: todo are defaults and can be omitted.

Frontmatter

Field	Required	Default	Meaning
`id`	no	generated on scan	Stable local task id
`title`	no	derived from body or filename	Display title
`state`	no	`active`	File lifecycle
`stage`	no	`todo`	Task progress

Unknown frontmatter fields are ignored by the current document model.

State and stage

state controls whether the file participates in task execution:

State	Meaning
`active`	Runnable when the stage allows it
`inactive`	Kept on disk but skipped
`archived`	Retired and listed only through archived views

stage tracks one-shot task progress:

Stage	Meaning
`todo`	Ready to claim
`running`	Claimed by one run
`done`	Completed
`failed`	Terminal failure; not retried automatically

Only tasks with state: active and stage: todo can be claimed. Claiming a task writes stage: running. The agent should update the task to done when the requested work is complete, or failed when the attempt cannot complete. Archive a task by setting state: archived or using the task archive command.

`.too` format

Tasks are not declared inside .too files. Toolang discovers Markdown files under tasks/ and runs them with the agent's normal .too program.

The task body becomes the run input, so a normal default thunk is enough:

agent.too

use skill openhat/reviewer
 
thunk:
  models = gpt-5
  skills = reviewer
  tools = shell, filesystem
 
  user:
    {{input}}

For a task file like:

---
title: Review docs
---
 
Review the changed docs and list release risks.

the agent receives Review the changed docs and list release risks. as the task input.

Notes

Runtime output, run history, and thread projection live in .runtime/runs.db; they are not appended to the task body. Task thread ids are runtime projections with the form task_<id>.