Tasks
Depth:
What it is
A task is a markdown file with YAML frontmatter in the aitasks/ directory, named t<N>_<short_name>.md (for example aitasks/t130_add_login.md). The frontmatter block carries fields like priority, effort, depends, status, labels, assigned_to, issue_type, boardcol; the free-form markdown body describes the work. Tasks persist exactly the same way source code does: as files committed to git. Every CLI command, TUI, and code agent skill operates on those files directly.
Why it exists
Treating task tracking as a problem that belongs in version control means the full history of every task is visible in git log, branches and worktrees can carry their own task state, and a code agent can read, write, and reason about tasks with the same tools it uses for source code. The frontmatter schema is intentionally small enough for an LLM to keep in context, but expressive enough to drive prioritization, dependency resolution, and Kanban-style triage.
How to use
The complete frontmatter schema and worked examples live in the Task File Format reference.
There are many ways to produce a task — they all just write a file into aitasks/. The most common entry points are ait create (typically launched from inside a TUI like Board or Brainstorm), code-aware capture from /aitask-explore and /aitask-wrap, and import flows like /aitask-pr-import. The Capturing ideas and Create tasks from code workflows walk through the recommended patterns.
See also
- Plans — the implementation contract written for an approved task
- Parent and child tasks — how complex tasks are decomposed
- Task lifecycle — the statuses a task moves through
- Locks — how only one agent works a task at a time
Next: Plans