Job Files

Jobs describe work for one agent. Tasks run one-shot work; chores repeat work on a schedule. Both use Markdown files with optional YAML frontmatter and a body containing the work instruction.

Location

The directory determines the job kind and its authored stage. Paths below are relative to the agent home, ${TOOLANG_ROOT}/agents/<agent>/.

Stage	Tasks	Chores	Meaning
`draft`	`drafts/tasks/<name>.md`	`drafts/chores/<name>.md`	Kept outside scheduling
`ready`	`tasks/<name>.md`	`chores/<name>.md`	Available to the scheduler
`archived`	`archive/tasks/<name>.md`	`archive/chores/<name>.md`	Retired

Files can use readable names such as review-api.md. Toolang assigns and saves a missing id when loading ready files, without changing their filenames.

Markdown format

Tasks

tasks/review-api.md

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

Chores

chores/check-prs.md

---
title: Check stale PRs
schedule: FREQ=HOURLY;INTERVAL=6
---
 
Check stale PRs and report actionable items.

Frontmatter

Field	Applies to	Required	Meaning
`id`	Both	No	Stable job identity; generated when absent
`title`	Both	No	Display title; falls back to body text or filename
`schedule`	Chores	No	RRULE string; defaults to `FREQ=HOURLY;INTERVAL=1`

IDs must be unique across task and chore files, including drafts and archives. Ready files and program declarations must also have distinct IDs.

Lifecycle

The authored stage comes from the file's directory. Frontmatter state and stage fields do not control execution. Move a file between the directories above to change its authored stage.

Runtime status is tracked separately: pending, running, done, failed, or canceled. A task's completion or failure does not rewrite its Markdown file. Changing a ready task's body requests another execution; a terminal task can also be reopened without changing its body. See the task commands for lifecycle operations.

Scheduling

Only ready chores participate in scheduling. The schedule field is parsed as an RRULE with dateutil.rrule. For example, FREQ=HOURLY;INTERVAL=6 repeats every six hours. Moving a chore to drafts or the archive removes it from scheduling.

Use chores for recurring checks and synchronization. A chore can create tasks for follow-up work that needs to be tracked separately.

`.too` format

Jobs can also be declared in the agent's .too program. The declaration name is the job ID; title and schedule use property syntax.

task review_api:
  title = Review API changes
 
  Review the API changes and summarize risks.
 
chore check_prs:
  title = Check stale PRs
  schedule = FREQ=HOURLY;INTERVAL=6
 
  Check stale PRs and report actionable items.

See Grammar for the declaration syntax.

Notes

The job body supplies the run input. By default, the runtime uses an agic or flow named task or chore for that kind, falling back to default. An explicit call in the body can select a different runnable.

Run history and results are stored separately from the authored file. Thread IDs use task_<id> and chore_<id>.