Kanban-md: A File-Based Approach to Project Management for AI-Assisted Development

The Friction of Traditional Kanban Tools

Many traditional Kanban tools, while initially appealing, often introduce more friction than they alleviate. The author notes a common cycle: initial enthusiasm, diligent card creation, followed by a gradual decline in usage as the effort to context-switch to a separate application and maintain the board outweighs its perceived benefits. This often leads to an outdated project board that no longer accurately reflects the actual state of development, creating a disconnect between planning and execution.

Kanban-md: A File-Native Solution

Kanban-md addresses these challenges by integrating project management directly into the development environment. Instead of a separate application, the Kanban board is a local directory, with each task represented by a markdown file. These files contain YAML frontmatter for structured data like status and priority, alongside free-form text for detailed documentation of tasks and rationales. This file-native approach ensures that the project board lives alongside the codebase, is version-controlled with every commit, and is easily accessible and readable in any text editor. This design significantly reduces context-switching and fosters a more integrated workflow.

Optimized for AI and Human Collaboration

A key strength of kanban-md lies in its seamless support for AI agent workflows. It provides a command-line interface (CLI) with commands for creating, listing, editing, and moving tasks, allowing AI agents to interact directly with the project board. The tool also prioritizes token efficiency for agent loops, making it suitable for automated collaboration. Beyond AI, kanban-md offers a human-friendly interactive TUI (Text User Interface) for visual browsing and editing within the terminal, providing a familiar Kanban experience without leaving the development environment. This dual functionality makes it an ideal foundational layer for projects involving both human and AI collaboration, ensuring that both parties read from and contribute to the same, consistent source of truth.

Benefits for Audit and Assurance

For audit and assurance professionals, kanban-md offers several compelling advantages. The version-controlled markdown files provide an inherent audit trail for every task, decision, and rationale. The ability to document trade-offs and rejections directly within task cards, as exemplified by the "rejection memo" card, enhances transparency and accountability. This level of detailed, versioned documentation can be invaluable for understanding project evolution, assessing decision-making processes, and ensuring compliance. While not suited for teams requiring deep enterprise integrations or advanced reporting dashboards, its simplicity and file-native design make it a powerful tool for developers, small teams, and AI-assisted projects seeking transparent, local-first workflows.