# kandown: the task board

The owner's to-do list is a [kandown](https://kandown.dev) board: one Markdown file per task in
`tasks/`, with settings in `.kandown/`. It replaced `NOTES.md` on 2026-10-24. This page records
how it works here, as checked on kandown 0.52.0. The full upstream documentation is one file at
https://kandown.dev/llms-full.txt (any docs page also works with `.md` added to its URL).

## Start of a session

```sh
kandown work           # the rules, our project instructions and the board, as Markdown (~1,900 tokens
                       # with 14 tasks)
kandown work t8        # the same, focused on one task
```

Our project rules are in `.kandown/kandown_work.md`; `kandown work` includes them under
"Project Instructions". `AGENTS.md` ends with the one-line pointer `kandown init` added; keep it.

## Columns

| Column | Role | What goes here |
|---|---|---|
| Backlog | backlog | Discussion notes (tag `discussion`) and ideas for later (tag `idea`) |
| Todo | ready | The owner's tasks |
| In Progress | active | What an agent is working on now |
| Review | review | Finished work waiting for the owner to check in the game ("done, please check") |
| Done | terminal | Checked by the owner. Only the owner moves tasks here |

## Commands

Task commands work offline and print data only on stdout (messages go to stderr), so they are
safe to capture. Set `KANDOWN_NO_UPDATE=1` in scripts.

```sh
kandown list                         # the board as a table; --json for data (no report field in it)
kandown show t8                      # one task file as it is on disk
ID=$(kandown create "Title" --to Todo -t discussion)   # prints only the new id, e.g. t15
kandown move t8 "In Progress"        # quote column names with spaces; "archived" archives
kandown doctor                       # checks kandown.json and every task's frontmatter
kandown                              # the owner's board: web page plus terminal UI (starts a daemon)
kandown daemon stop                  # stop that daemon
```

- **`--help` is not safe.** `kandown init --help` ignored the flag and ran `init` in the current
  folder, which also started a daemon. Use `kandown help` or the docs, never `<command> --help`.
- `kandown init` starts the web daemon unless given `--no-open`. With an existing empty `tasks/`
  it created no sample tasks.
- `kandown create` names the file from the id and the title: `tasks/t8_fog_war_unexplored.md`.
  Find it with `tasks/<id>_*.md`; don't rename it.
- `kandown create` has no body option: write the body into the file after creating it.
- `depends_on` blocks a move to Done until the listed tasks are done.

## A task file

```markdown
---
id: t8
title: Fog of war for unexplored areas
status: Review
created: 2026-10-24
updated: 2026-10-24T04:41:46Z
tags: [discussion]
report: |
  (agent) What changed, in a few lines.
  To check: how the owner sees it in the game.
---

## Context

- The owner's note, word for word.

## Subtasks

- [x] A step
  report: What actually happened.
```

- Only `id`, `title` and `status` are required. Unknown keys are kept.
- **`report`** is the completion summary the board shows prominently. A multi-line `report: |`
  block works (kandown's parser reads block scalars); `kandown doctor` accepts it.
- `## Context` holds why the task exists: here, the owner's own words. `## Subtasks` is a
  checklist whose items can carry a `report:` line.
- Editing files directly is supported; the board notices changes. Run `kandown doctor` after.

## Files

| Path | Committed | What it is |
|---|---|---|
| `tasks/*.md`, `tasks/archive/` | yes | The tasks; the folder is the whole state, no index |
| `.kandown/kandown.json` | yes | Columns, column instructions, workflow, which fields show |
| `.kandown/kandown_work.md` | yes | Our project rules for agents |
| `.kandown/agents.json`, `README.md`, `.gitignore` | yes | Written by `kandown init` |
| `.kandown/kandown.html` | no (`.gitignore`) | The 6.5 MB web app; `kandown init` / `kandown update` rebuild it |
| `.kandown/daemon.json` | no (`.kandown/.gitignore`) | The running daemon's port and access token |

## Codex and kandown

`kandown list` and `kandown doctor` were checked inside Codex's `workspace-write` sandbox and
work; the other task commands also only read and write files in the repo. Not checked under
Codex: the web daemon (`kandown`
with no command), which serves a page on a local port. Codex's `workspace-write` sandbox blocks
network sockets (it is why headless Chrome crashed under Codex until runs passed
`-c sandbox_workspace_write.network_access=true`).