Tasks

A task is a single Markdown file in tasks/. Everything below is a description of what goes in that file — the UI, the terminal and the CLI are three editors for the same thing.

Creating a task

Quick-add syntax

The fastest path in both the web board and the terminal UI is one line of text. Kandown parses the metadata out of it:

Fix login p1 #backend #security @chacha due:friday

Everything left over becomes the title.

From the CLI

kandown create "Refactor auth middleware" \
  --priority P1 \
  --tag backend --tag security \
  --assignee chacha \
  --to "In progress"

The command prints the new id on stdout and nothing else, so $( … ) captures exactly one value. Add --json if you want the whole task object back.

Fields

Subtasks

Subtasks are a plain Markdown checklist under a ## Subtasks heading:

## Subtasks
- [x] Extract the token parser
  report: Moved to src/auth/token.ts, added unit tests for expiry.
- [ ] Cover the refresh path with tests
- [ ] Delete the legacy middleware

Two things make them more than a checklist:

• Per-step descriptions — indented prose under a step, for context that does not belong in the title.
• report: lines — what actually happened when the step was completed. This is the field that turns a finished task into a work log rather than a row of green ticks, and it is where agents are expected to write their results.

In the UI, subtasks can be reordered from the keyboard and each carries its own description and report editor.

Dependencies

depends_on: [t7, t12]

A task with unresolved dependencies cannot be moved to the terminal column. The gate lives in the shared core, so the refusal is identical whether the move comes from a drag in the browser, an m in the terminal UI, or kandown move in a script — the CLI cannot route around what the UI refuses.

Blocked tasks are annotated as such in the board digest that agents read, so an agent picking up work never selects something it cannot finish.

Owner type

Every task is owned by a human or an ai. It is a filter, not a permission: it lets you look at "what am I doing" and "what are the agents doing" separately on a shared board.

Templates

Recurring shapes — a bug report, a release checklist, a spike — can be saved as templates and applied when creating a task, so the subtask list and default fields come pre-filled.

Archiving and deleting

Archiving moves the file to tasks/archive/. It stays readable, greppable and in git; it simply leaves the active board.

kandown move t14 archived

Deleting removes the file. In the web UI, deletion is guarded behind a double-click, and a whole column can be archived or deleted in bulk when you are cleaning up.

External changes

Kandown watches the task folder. If you edit a task in your editor, or an agent writes to it while the board is open, the change is detected and surfaced rather than silently overwritten.