44r0n7andClaude Opus 5.5
e0525c1cfb
Each note is a task in tasks/ with the owner's words under ## Context; the board rules are in .kandown/kandown_work.md and docs/kandown.md explains how kandown works here. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# 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`).
|