Move the to-do list from NOTES.md to a kandown board

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>
This commit is contained in:
2026-10-24 00:44:22 -04:00
co-authored by Claude Opus 5.5
parent aadcbc6efb
commit e0525c1cfb
28 changed files with 579 additions and 58 deletions
+17 -17
View File
@@ -11,7 +11,8 @@ The owner (the user) directs the work and is the real playtester. You build, tes
## Start of every session
1. Read `NOTES.md`. It is the user's to-do inbox (see "Working from NOTES.md" below).
1. Run `kandown work`. It prints the user's task board and the rules for working it (see
"Working from the task board" below).
2. Read `docs/PROJECT_MAP.md` before searching the code. It says where everything lives. Its
index lists every top-level function and variable by file.
3. Before changing how the game plays, read the relevant part of `docs/DESIGN.md`. Many choices
@@ -39,24 +40,21 @@ These rules matter more than speed.
ask first. If the choice is small or easy to undo, take the sensible reading, say which one you
took, and carry on.
## Working from NOTES.md
## Working from the task board
`NOTES.md` belongs to the user. They add notes at any time and ask you to work on them ("do the
notes", "do the belt note"). Work on notes only when asked.
The user's to-do list is a kandown board: one Markdown file per task in `tasks/`. **Read
`docs/kandown.md` before using it**: it says how the board works here, which commands are safe
(never run `kandown <command> --help`: it runs the command), and what a task file looks like.
The rules for working the board are in `.kandown/kandown_work.md`, and `kandown work` prints
them. In short:
- **Kinds of note.**
- Tasks ("add...", "make...", "fix...") are built.
- Discussion notes ("let's think about...", "brainstorm...", "what can we do about...",
"let's talk about...") get options with trade-offs and a recommendation. Do not build them
until the user decides.
- Questions get answers.
- **Keep the user's wording.** Never rewrite or tidy a note. If you need to add context, add a
sub-bullet that starts with `(agent)`.
- **When a task is finished**, move the note, word for word, into the "Done, please check"
section at the bottom. Under it, add an `(agent)` sub-bullet saying what changed and how to
check it in the game. Do not delete it: the user deletes it after checking. If the user says
it is not fixed, move it back up and add their feedback as a sub-bullet.
- **Log your work.** Add an entry at the top of `docs/agent-log.md` with the date, the note,
- Work on tasks only when asked. Todo tasks are built; Backlog tasks tagged `discussion` get
options with trade-offs and a recommendation, and nothing is built until the user decides.
- Never reword the user's words in a task's `## Context`. Add your notes as subtasks with
`report:` lines, or in the `report` field.
- When a task is finished, move it to **Review** with a `report` saying what changed and how to
check it in the game. Only the user moves tasks to Done.
- **Log your work.** Add an entry at the top of `docs/agent-log.md` with the date, the task,
what changed, the files touched, the tests run, and anything left open.
- **Record decisions.** When the user decides something about the design, add it to the
decisions list in `docs/DESIGN.md` with the date and the reason they gave.
@@ -178,3 +176,5 @@ screenshots and the pitfalls. The essentials:
- Never commit secrets: tokens, passwords, or keys.
- Work happens one agent at a time. If running several agents side by side is set up later,
this section will say how they coordinate.
This project uses Kandown. Before task work, run `kandown work` and follow its output. <!-- kandown:agent-ref -->