deepgrain-foundry/docs/kandown.md

kandown: the task board

The owner's to-do list is a kandown 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

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.

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

---
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).