Backlog.md: Terminal Kanban Board for Managing Tasks with AI Agents — Alex Gavrilescu, Funstage

Key Concepts

• Backlog MD: An open-source CLI tool for project management designed for AI agents and humans, featuring a terminal-based Kanban board.
• Markdown Tasks: Tasks are stored as markdown files in a Git repository, containing front matter (metadata) and a description with acceptance criteria.
• Context Engineering: Dividing large features into smaller, atomic markdown tasks to manage AI agent context windows and ensure focused implementation.
• MCP (Multi-agent Communication Protocol): A protocol used by Backlog MD to expose information, instructions, and tools to AI agents.
• Resources (MCP): Specific guides provided via MCP to instruct AI agents on Backlog MD's workflow, including task creation, execution, and completion.
• Tools (MCP): Commands exposed via MCP that allow AI agents to interact with Backlog MD, such as searching, viewing, creating, and updating tasks.
• Kanban Board (Terminal UI): A visual representation of tasks in different stages (e.g., To Do, In Progress, Done) accessible directly within the terminal.
• Review Process: A multi-stage review system for AI-generated work, including task creation, implementation plan, and code review.

Backlog MD: A Project Management Tool for AI Agents and Humans

This presentation introduces Backlog MD, a novel project management tool designed to bridge the gap between human developers and AI agents, particularly addressing the limitations of AI context windows and ensuring efficient task management. The core philosophy revolves around breaking down large features into smaller, manageable markdown tasks.

Terminal Kanban Board and Task Structure

Backlog MD offers a full Kanban board experience directly within the terminal. Tasks are visualized in columns representing different statuses (e.g., To Do, In Progress, Done). Each task is stored as a markdown file within a Git repository.

• Markdown Task Structure:
  • Front Matter: Contains metadata such as task ID, title, labels, and other relevant fields.
  • Description: A clear explanation of the task's purpose.
  • Acceptance Criteria: Testable and verifiable conditions that define the successful completion of the task. These are crucial for ensuring the AI agent understands the intent and for later verification.
  • Implementation Notes: (Optional) Notes left by developers or AI agents regarding the implementation.

Developing the "Move Task" Feature

The presentation demonstrates the development of a new feature for Backlog MD: the ability to move tasks between status columns and reorder tasks within the same column using keyboard navigation. This process highlights the workflow for interacting with AI agents.

• Requirements for "Move Task" Feature:
  • Press M to toggle "move mode."
  • The current task is highlighted.
  • Use arrow keys (up/down) to reorder tasks within a column.
  • Use arrow keys (left/right) to change the task's status column.
  • Press M or Enter to commit the move.
  • Press Esc to cancel the move.
  • Instructions for this functionality are displayed in the footer.

AI Agent Workflow: Task Creation and Implementation Plan

The process of creating a new task and generating an implementation plan using an AI agent (Claude) is detailed.

1. Task Creation:

   • The user provides a human-readable description of the desired feature.
   • The AI agent, Claude, first understands the Backlog MD system and its workflow by reading provided resources.
   • Claude then reads the task creation guide to understand the required fields and format.
   • Finally, Claude creates the task as a markdown file, populating the description and acceptance criteria.
   • Example Task Description: "Add the move mode feature in the twoe comban board that allows users to interactively reorder tasks within columns and move tasks between status columns using keyboard navigation. This provides a more intuitive way to reorganize tasks without needing to use CLI commands or edit files directly."

2. Implementation Plan Generation:

   • After task creation, the AI agent is instructed to create an implementation plan.
   • The agent researches existing code, documentation, and the internet to understand where the feature should be implemented.
   • The output includes an architecture overview, implementation steps, and specific files to be modified.
   • Review Point 1 (Task Creation): This is the first checkpoint where a human can verify if the AI agent understood the intent by reviewing the description and acceptance criteria.
   • Review Point 2 (Implementation Plan): This is a critical review step where a senior engineer can assess if the AI agent is heading in the right direction by examining the proposed implementation plan.

Under the Hood: MCP and Resources

Backlog MD utilizes an MCP server to facilitate communication and provide tools to AI agents.

• MCP Server: Exposes information, instructions, and tools to AI agents.
• Resources: Special features of MCP that provide AI agents with essential knowledge about Backlog MD.
  • Workflow Overview: Explains what Backlog MD is and its purpose.
  • Task Creation Guide: Details how to create tasks and required fields.
  • Task Execution Guide: Outlines steps for AI agents when implementing tasks, including status changes and self-assignment.
  • Task Completion Guide: Describes how to complete a task, verify acceptance criteria, and meet the definition of done.
• Tools: Commands exposed via MCP that allow AI agents to interact with Backlog MD.
  • Search tasks
  • View task details
  • Create tasks
  • Update tasks and acceptance criteria
  • Update task status

AI Agent Workflow: Code Implementation

Once the implementation plan is reviewed and approved, the AI agent proceeds to write the code.

• Execution: AI agents (Claude, Gemini, etc.) learn about the task, description, acceptance criteria, and plan.
• Definition of Done: Implementing all acceptance criteria and moving the task to "Done."
• The presentation shows the AI agent implementing the "move task" feature.

Backlog MD Workflow Summary

The workflow can be summarized as follows:

1. Human Creates Tasks: Humans can create tasks directly or ask AI agents to do so based on human descriptions.
2. AI Agent Creates Tasks: AI agents use Backlog commands to create and populate tasks with necessary sections.
3. Human Assigns Tasks: Humans can assign tasks to AI agents (e.g., "Hey Claude, can you please implement task 316?").
4. AI Agent Implements Tasks: The AI agent executes the task, writes code, and moves it to "Done" upon completion.

Demonstration of Implemented Feature

The presentation demonstrates the newly implemented "move task" feature in the terminal Kanban board.

• Pressing M highlights the task.
• Arrow keys allow reordering within a column and moving between status columns.
• The move can be committed or canceled.
• The feature allows moving a task back to "In Progress" if issues are found.

Advantages of Backlog MD and Context Engineering

The effectiveness of Backlog MD is attributed to several key advantages:

• Context Engineering: Storing tasks as markdown files allows for precise definition of what an AI agent should implement within a single task, preventing context window limitations and unwanted feature creep.
• Atomic Tasks: Smaller, atomic tasks make it easier to roll back, modify specifications, and restart implementation if errors occur.
• Well-Defined Scope: Acceptance criteria clearly define what is included and excluded from a feature.
• Testability: Unit tests can verify if acceptance criteria are met.
• Three-Stage Review Process:
  1. Task Creation Review: Verify AI understanding of intent (description and acceptance criteria).
  2. Implementation Plan Review: Assess the AI's direction.
  3. Code Review: Final verification of the implemented code.
• Parallel Development: Tasks can be worked on in parallel using Git, provided there are no dependencies.

Backlog MD: Technical Details and Features

• Open-Source: MIT license.
• Interfaces: Terminal User Interface (TUI) and Web Interface.
• AI Agent Interaction: Supports CLI commands and MCP (preferred native way).
• Cross-Platform: Works on most major operating systems.
• No External Dependencies: Does not require extra APIs, tools, databases, or accounts.
• Git Integration: Tasks are hosted on a Git repository, ensuring team-wide synchronization. Backlog MD checks task status even if updated on different branches.
• AI-Generated Code: Approximately 99% of Backlog MD's code was written by AI agents, with the initial instructions and first three tasks written by the presenter.

Conclusion and Next Steps

Backlog MD offers a robust solution for managing projects with AI agents, emphasizing clear task definition, iterative development, and a structured review process. The presenter encourages users to visit backlog.mmd to learn more and experiment with the tool.