Task Structure

Here is a sample task file (.kanbn/tasks/task-name.md):

---
created: 2021-03-18T02:08:42.293Z
updated: 2021-03-18T02:08:42.293Z
tags:
  - TagName
assigned: Username
progress: 0.5
started: 2021-03-21T04:58:38.653Z
completed: 2021-03-21T04:58:38.653Z
due: 2021-03-21T04:58:38.653Z
plannedStart: 2021-03-20T04:58:38.653Z
plannedFinish: 2021-03-24T04:58:38.653Z
---

# Task Name

Task description...

## Sub-tasks

- [ ] This is an incomplete sub-task
- [x] This sub-task has been completed

## Relations

- [duplicates test-task-1](test-task-1.md)
- [obsoletes test-task-2](test-task-2.md)

## Comments

- author: Username
  date: 2021-03-31T07:47:05.775Z
  This is a comment...

## History

- type: created
  date: 2021-03-18T02:08:42.293Z
  column: Backlog
- type: moved
  date: 2021-03-21T04:58:38.653Z
  fromColumn: Backlog
  toColumn: In Progress
- type: progress
  date: 2021-03-22T09:30:00.000Z
  fromProgress: 0.25
  toProgress: 0.5
- type: archived
  date: 2021-03-31T07:47:05.775Z
  fromColumn: In Progress
- type: restored
  date: 2021-04-01T10:00:00.000Z
  toColumn: Backlog

The task file can optionally begin with YAML front-matter containing task metadata.

There should be a single level-1 heading at the top of the markdown body containing the task name.

The task description should appear below the title. The description can be of any length and can contain markdown.

The following level-2 headings are reserved for special purposes (## Metadata, ## Sub-tasks, ## Relations, ## Comments and ## History). Any other level-2 heading is treated as part of the description, as is a heading at any other level - a ### Sub-tasks heading in a description is description content, not the task's sub-tasks.

Headings inside fenced code blocks are ignored, so a shell or Python comment like # install deps in a ```bash block stays where you wrote it.

Metadata#

The 'Metadata' heading should be followed by a code block containing YAML. The 'yaml' info-string is not required, but might help with syntax highlighting in some editors.

Task metadata will be merged with YAML front-matter if any is present.

Note: when a task is saved, all task metadata will be placed into YAML front-matter. The 'Metadata' heading is still supported for backwards-compatibility.

created: 2021-03-18T02:08:42.293Z
updated: 2021-03-18T02:08:42.293Z
tags:
  - TagName
assigned: Username
progress: 0.5
started: 2021-03-21T04:58:38.653Z
completed: 2021-03-21T04:58:38.653Z
due: 2021-03-21T04:58:38.653Z

created#

The date and time that the task was created. This is automatically populated when the task is created using kanbn add.

updated#

The date and time that the task was last updated. This is automatically populated when the task is modified, renamed, or moved to another column.

tags#

An array of tags to apply to this task.

assigned#

The name of the user this task is assigned to. This is free text: any string is a valid assignee, and Kanbn never rejects or rewrites one.

A workspace can declare a list of contributors, which gives each person a canonical spelling, autocompletes this field in the interactive prompts and lets kanbn find --assigned @me work. Contributors are advisory — assigned stays free text either way, and a name that isn't in the list is still perfectly valid.

A task has one assignee. assigned is a single string in the schema, the filters, the board template and the reporting commands, and there is no multiple-assignee form.

progress#

The amount of progress for this task. This should be between 0 (not started) and 1 (complete).

Progress is not derived from sub-tasks. If the task has no progress value it counts as 0, and a task that is considered complete always counts as 1 regardless of this value. A task is considered complete if its completedField — completed by default — has a date. The column a task sits in doesn't make it complete; see Index Structure.

started#

The date and time that the task was started.

completed#

The date and time that the task was completed.

due#

The date and time that the task is due to be completed.

plannedStart#

An optional date and time used as a preferred start point for gantt scheduling.

plannedFinish#

An optional date and time used as a preferred finish point for gantt scheduling.

Custom fields#

Any other metadata field is preserved but otherwise ignored, unless it is declared in the customFields project option. Declared custom fields can be set with kanbn add and kanbn edit, searched with kanbn find, sorted with kanbn sort, filtered in views, and interpolated into the board's taskTemplate.

Workload#

A task's workload is not stored in the file - it is calculated from the task's tags. It is the sum of the values of its workload tags, or defaultTaskWorkload if it has none.

Sub-tasks#

This should be a list of strings. Each string can optionally start with [ ] (incomplete) or [x] (completed).

Relations#

This should be a list of links to other task files. The link text can optionally begin with a relation type.

The depends-on relation type is reserved for gantt scheduling. It means the current task should not start until the linked task has finished.

Comments#

An array of comments, where each comment has an author and date property, and some text.

author is free text, exactly like assigned, and it is optional — a comment added on a machine with no resolvable user has an empty author rather than failing to save. When the workspace declares contributors, the default author is the canonical name for the current user.

History#

An optional array of structured lifecycle events used for richer timeline reporting (including burndown).

Supported event types:

• created: requires date and column
• added: requires date and column — the task joined a board
• removed: requires date — the task left a board
• moved: requires date, fromColumn, toColumn
• progress: requires date, fromProgress, toProgress
• archived: requires date, fromColumn
• restored: requires date, toColumn

Notes:

• History entries are stored in the reserved ## History section as list items.
• date should be an ISO timestamp.
• Every event carries an optional author, naming the current user at the time it happened. The key is omitted entirely when there is no resolvable user, so a machine with no git identity writes exactly the history it always has.
• Any other additional field is preserved if present.
• An event type this version of Kanbn doesn't recognise is preserved and skipped rather than rejected, so a task file written by a newer version stays readable.

Board attribution#

In a workspace with multiple boards, an event carries an optional board key naming the board it happened on:

## History

- type: moved
  date: 2026-07-14T09:12:00.000Z
  fromColumn: Ideas
  toColumn: Designing
  board: design

Events on the main board carry no board key, so a single-board workspace writes exactly the history it always has, and every existing task file stays valid.

archived and progress events are never board-scoped: archiving removes a task from every board, and progress is a property of the task rather than of a board.