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/.

The number in the filename is the task’s identity, so the convention is load-bearing rather than cosmetic: it is how a listing row, a board card, a lock, an archive entry and a dependency reference all resolve back to the file. ait create always assigns one. A file written into aitasks/ by hand can end up without it, and such a file is unaddressable: ait ls skips it and warns rather than listing a row nothing can act on, and a name further from the convention is not listed at all. Either way the file is invisible to the tooling, so the fix is to rename it to the convention.

---
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

Nested fields: artifacts and attachments

Every other field above is a flat scalar or a flat list. These two are lists of mappings, and they are the only place the header nests:

artifacts:
  - handle: art:trail-shadow-review-loop
    kind: implementation_trail
    name: "Shadow review-loop automation: landing order"
attachments:
  - hash: sha256:1f8b034f74a1…
    name: crash-log.txt
    mime: text/plain
    size: 4821
    added_at: 2026-08-14 09:12
    backend: local

Neither is hand-edited. artifacts entries are written by ait artifact and attachments entries by ait attach; both commands manage the blob, the manifest and the task file as one commit, so editing the block by hand desynchronises it from the store.

Fields the workflow writes for you

Some rows above are marked Framework-derived or “written by the workflow only” — active_gates and its three companions, risk_code_health, risk_goal_achievement, risk_mitigation_tasks, and plan_approved_at. The ait update flags that write them exist but are deliberately not documented: they are internal surfaces the workflow calls at defined points, and setting one by hand produces a value the next pick recomputes or clears. Where a field is meant to be set by a person, the flag is named in its own row — see verification_baseline and boardgroup.

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
enhancement
feature
performance
refactor
style
test
manual_verification

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