# Tasks

Creating tasks, the fields they carry, subtasks with reports, dependencies, and templates.

> Kandown documentation — https://kandown.dev/docs/guides/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
```

| Token | Sets |
|---|---|
| `p1` … `p4` | Priority |
| `#tag` | A tag — repeat for several |
| `@name` | Assignee |
| `due:friday`, `due:2026-08-01` | Due date, natural language or ISO |

Everything left over becomes the title.

### From the CLI

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

| Field | Meaning |
|---|---|
| `id` | Stable identifier. Auto-generated, or set with `--id` |
| `title` | Task title |
| `status` | Board column, from `board.columns` in `kandown.json` |
| `order` | Sort position within the column |
| `priority` | `P1`–`P4`, highest to lowest |
| `tags` | Free-form labels |
| `assignee` | A username or an agent name |
| `ownerType` | `human` or `ai` — drives owner filtering |
| `due` | Due date; drives the due-date banner |
| `epic` | Groups related tasks; available as a group-by |
| `depends_on` | Ids of tasks blocking this one |
| `created` | Creation date |
| `report` | Completion summary in Markdown, shown prominently in the UI |

## Subtasks

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

```markdown
## 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

```yaml
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.

```bash
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.