The five stages
backlog, to-do, in-progress, review, done — the directory a task file sits in is its status, and there is no other source of truth.
The flow is linear:
backlog → to-do → in-progress → review → done
backlog/
Where new tasks are written and where they wait. A backlog task may be rough, incomplete, or fully specified — what it has in common with its neighbours is that nobody is working on it. Most tasks live here for most of their life.
to-do/
Picked up and queued to work on next. Moving a task from backlog/ to to-do/
is a commitment to do it soon, so keep this directory short — a long to-do/ is
just a second backlog.
in-progress/
Actively being worked on right now. Anything here should have someone (or an
agent session) attached to it. If work stalls, move it back to to-do/ or
backlog/ rather than leaving it parked — a stale in-progress/ makes the board
lie about what is happening.
Implementation plans (created via Claude Code's plan mode) are stored in plans/
and can be referenced from the task file.
review/
The work is built and awaits judgment: tests written and passing, a PR open
(see "Pull requests"), behaviour checked in the running app, edge cases
probed. A task sitting here has code but not yet confidence. If review turns
up problems, move it back to in-progress/.
done/
Finished and merged. Completed task files are kept as a record of what was built and why — they are the closest thing we have to design history, so don't delete or trim them.
reference/ (beside tasks/, not a stage)
Supporting documents that tasks can link to — external specs, API documentation,
research notes, screenshots, competitive analysis, regulatory references, etc.
These don't move through the workflow; they're stable resources. Reference them
from task files using relative links — two levels up from a stage directory
(e.g. [the payments API spec](../../reference/payments-api.md)).
Moving a task
When moving a task between stages:
- Update the Status field in the task file header
- Move the file to the new directory
- Add any notes about why it's moving (e.g. "approach agreed, starting build")
Moves are not always forward. Going back a stage is normal and expected — verification failing, or an approach not surviving contact with the code, should move the task backwards rather than being worked around in place.