44r0n7andClaude Opus 5.5
b4245871ae
Also: board rule to write tasks from chat in our own words, task descriptions rewritten that way, and a note on lost web-board descriptions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
108 lines
4.9 KiB
Markdown
108 lines
4.9 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.
|
||
- **Descriptions typed on the web board can be lost.** On 2026-10-24 the owner created t16–t19
|
||
on the web board with descriptions; the files were saved with a title and no body. The owner
|
||
believes it is a bug in the web daemon (not investigated). A task with only a title may have
|
||
had a description: ask the owner, then write their words under `## Context` yourself.
|
||
|
||
## 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`).
|