Why MD Kanban stores every card as a markdown file on disk, how the first browser board was built around that idea, and the two contracts that let AI agents manage it.
The problem I actually have: I run several AI coding agents across several projects, and I lose track of what each one is doing. Jira and Linear keep their state behind an API, so an agent needs credentials and a connector before it can move a card. A folder is something an agent can already write to. That observation is the entire project.
A card is a file
MD Kanban treats every task as one markdown file with YAML frontmatter: id, status, priority, assignee, dueDate, created, modified, labels, order, then a # title and a body. Each connected folder is a project. Subfolders inside it group work, auth/ or billing/. Dragging a card from To Do to Done rewrites the file's status field. An agent edits the same file from its side with no plugin and no permissions dance.
The format is deliberately boring. Any tool that reads text can participate, including future me with a plain text editor.
The scaffold
Vue 3 with Vite and TypeScript, Tailwind for styling, shadcn-vue style components built on reka-ui. The board itself is five columns with HTML5 drag and drop, a search and filter bar, and a slide-in editor with markdown preview that autosaves back to the file. First run ships two demo projects stored in the browser so the board is never empty.
Local folders connect through the File System Access API, which means Chrome or Edge, with handles persisted in IndexedDB so projects survive reloads. Firefox and Safari fall back to the demos. That limitation is real and it is also the reason the desktop build exists later.
The contract, twice
Agents need rules, so the repo ships them twice. AGENTS.md at the root states the folder layout, the frontmatter schema, and the allowed operations. skills/md-kanban/SKILL.md packages the same knowledge as an installable skill for OpenCode, Claude Code, and anything skills.sh compatible. Both say the same thing: read, add, update, move, delete, and confirm before creating more than three files at once.
Where it stands
The browser board works end to end against real folders: connect, drag, edit, create, delete, all landing in files on disk. The project tracks its own remaining build as task files inside itself, which is both dogfooding and the fastest way to notice when the format fights back.
