Task files
A task is a markdown file with a numbered name and a short header. Status is the only field the board enforces.
Each task is a markdown file with a descriptive filename
(e.g. 01-document-handling-review.md). Numbers are allocated in creation order
and stay with the file for life — they do not renumber when a task moves stage.
Start new tasks from tasks/task-template.md — copy it into backlog/ and
fill it in. Its sections earn their keep: Context and What-to-build are what
a work agent gets as its brief, Acceptance is what reviews judge against,
and a non-empty Open-questions section makes an agent refuse the task
(NOT READY) rather than guess. The template itself is never listed on the
board (only stage directories are read).
The file should have at minimum:
# Task title
**Status:** Backlog | To Do | In Progress | Review | Done
**Priority:** High | Medium | Low
Use those exact status values — nothing else (not "Not started", "WIP", etc.) —
and keep the status in step with the directory the file sits in. Priority may
carry a short justification after the level
(e.g. Medium — foundational for any real environment).
Every header field, and who writes it:
| Field | Required | Value | Written by |
|---|---|---|---|
| Status | yes | Backlog · To Do · In Progress · Review · Done (Archived for a card in tasks/archive/) |
you, or the board on a move |
| Priority | yes | High · Medium · Low, optionally followed by a short justification |
you |
| Type | no | Discovery · Bug · Feature · Refactor · Chore · Phase |
you |
| Assignee | no | a name, taken from git config user.name |
the board on a claiming move, or you by hand |
| Depends on | no | task numbers or external preconditions, comma-separated | you |
| PR | no | the pull request url | the board when it opens one |
Status is the field the board holds you to: a header that disagrees
with the directory the file sits in is flagged status drift.
Assignee and PR it writes and reads itself. The rest are for
whoever picks the next card.
An optional Type line can record what kind of work the task is, when that isn't obvious from the title:
**Type:** Discovery | Bug | Feature | Refactor | Chore | Phase
Type is orthogonal to status. A discovery task — research, scoping, spiking an approach — moves through the same five stages as everything else; "discovery" describes the work, not where it sits on the board.
An optional Assignee line records who holds the card:
**Assignee:** ronald
The board writes it when a move claims the card (see "Claiming a card") and
removes it when the card is walked back to backlog/; on done/ cards it
stays as history. Editing it by hand is fine — it is a plain header field,
and a hand-move should update it alongside Status.
An optional Depends on line can name what must land first — task numbers or external preconditions — so sequencing lives in the header instead of prose asides:
**Depends on:** 03, 05
The board parses the task numbers out of the line (prose preconditions are left for the reader) and nothing enforces them yet: they inform whoever picks the next card, and guard what a phase may start.
The rest of the file is freeform — description, research findings, approach, open questions, whatever is relevant to the current stage.