Task File Format

File Structure

Tasks are markdown files with YAML frontmatter in the aitasks/ directory. Task files use the naming convention t<number>_<name>.md. Executed task files are stored in aitasks/archived/ and their associated plan files in aiplans/archived/.

---
priority: high
effort: medium
depends: []
issue_type: feature  # See aitasks/metadata/task_types.txt for valid types
status: Ready
labels: [ui, backend]
created_at: 2026-01-15 10:00
updated_at: 2026-01-15 10:00
---

## Task description here

Detailed description of what needs to be done.

Frontmatter Fields

Topic Anchoring

The optional anchor field groups related tasks around a topic root without making them children of that root. A root task omits the field; its own task id is its topic key. A related task stores the root id in bare form:

anchor: 130

Anchors are written by aitask_create.sh --anchor <id> or derived with --followup-of <source_id>, which always resolves to the source task’s root rather than chaining follow-ups together. Children created with --parent inherit the parent’s root, so a topic can include a parent, its child tasks, and loose follow-ups in one board lane.

Use aitask_update.sh --batch <id> --anchor <root> to move a task to a topic, or --anchor "" to clear the field and make the task its own root again.

Status Workflow

Ready → Editing → Implementing → Done → Archived
                              ↘ Folded (merged into another task)

• Ready — Task is defined and available for implementation
• Editing — Task is being refined (description, requirements)
• Implementing — Active development in progress (assigned to someone)
• Postponed — Deferred for later
• Folded — Task was merged into another task via /aitask-fold or /aitask-explore; deleted on archival of the primary task
• Done — Implementation complete, pending archival
• Archived — Task and plan files moved to archived/ directories

Parent-Child Hierarchies

Tasks support parent-child hierarchies for breaking complex work into subtasks:

• Parent tasks live in aitasks/ (e.g., aitasks/t10_implement_auth.md)
• Child tasks live in aitasks/t<parent>/ (e.g., aitasks/t10/t10_1_add_login.md)
• Child plans live in aiplans/p<parent>/ (e.g., aiplans/p10/p10_1_add_login.md)

Parent tasks track remaining children via the children_to_implement frontmatter field. When all children are complete, the parent is automatically archived.

Child task IDs use the format t<parent>_<child>_<name>.md where both parent and child identifiers are numbers only. Do not insert tasks “in-between” (e.g., no t10_1b). If you discover a missing step, add it as the next available number and adjust dependencies.

Archive Storage

Completed tasks move through the archive lifecycle:

1. Archived directory — aitasks/archived/t150_feature.md (loose files, recent)
2. Numbered archives — aitasks/archived/_b0/old1.tar.gz (compressed bundles)

The numbering scheme groups tasks by hundreds:

Computation:

• bundle = task_id / 100 (integer division)
• directory = bundle / 10 (integer division)
• path = archived/_b{directory}/old{bundle}.tar.gz

The _b prefix on directory names avoids collision with task child directories (t<N>/).

Child tasks are archived with their parent’s bundle (e.g., t130/t130_2_subtask.md goes into old1.tar.gz alongside t130_feature.md).

Plan archives follow the same scheme under aiplans/archived/.

Customizing Task Types

Valid issue types are defined in aitasks/metadata/task_types.txt (one type per line, sorted alphabetically). The default types are:

bug
chore
documentation
feature
performance
refactor
style
test

To add a custom type, simply add a new line to the file. All scripts (ait create, ait update, ait board, ait stats) read from this file dynamically.

Next: Review Guide Format