Tokenless

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

Alex Gavrilescu introduces Backlog.md, a Git-based project management tool designed to structure AI-driven development. By breaking down features into Markdown tasks and using a multi-step review process, it helps prevent AI agents from running out of context or deviating from requirements, enabling a more predictable and efficient workflow.

3 min read
Backlog.md: Terminal Kanban Board for Managing Tasks with AI Agents — Alex Gavrilescu, Funstage
source: https://www.youtube.com/watch?v=zMXKhhwiCIc

A common frustration when working with AI agents is that they can work for extended periods, only to go in the wrong direction or run out of their context window mid-task. Backlog.md is a tool and workflow designed to solve this by breaking down large features into smaller, well-defined Markdown tasks managed directly within a Git repository. It provides a structured project management framework for both AI agents and human developers.

Core Features of Backlog.md

Backlog.md is an open-source, cross-platform CLI tool with a Terminal User Interface (TUI) that functions as a complete Kanban board in the terminal. It requires no external databases or accounts, as all tasks are stored as Markdown files in the project’s Git repository, ensuring they are versioned and synced for the entire team.

A task in Backlog.md is a Markdown file structured with:

  • Front Matter: Contains metadata like task ID, title, and labels.
  • Description: A detailed explanation of the feature’s purpose.
  • Acceptance Criteria: A clear, testable list of requirements that define when the task is complete.
  • Implementation Plan: A step-by-step plan, often generated by the AI agent, detailing the files to be modified and the approach to be taken.

The AI-Driven Development Workflow

The workflow is designed around a series of review checkpoints to ensure the AI agent stays on track.

  1. Task Creation: A human provides a high-level requirement. The AI agent then uses this to create a formal task in Backlog.md.
  2. Review Point #1 (Intent): The human developer reviews the agent-generated task, focusing on the Description and Acceptance Criteria. This crucial first step verifies that the agent has correctly understood the core intent of the feature before any implementation begins.
  3. Implementation Plan Generation: The agent is instructed to create an implementation plan. To do this, it analyzes the existing codebase, documentation, and the task’s requirements to determine the best approach.
  4. Review Point #2 (Direction): A senior developer reviews the Implementation Plan. This is the most important review step, as it validates the technical direction and ensures the agent’s proposed changes are sound before writing code.
  5. Code Execution: Once the plan is approved, the AI agent proceeds to write the code to meet all acceptance criteria.
  6. Review Point #3 (Code): The final generated code is reviewed by the human developer.

How AI Agents Interact with Backlog.md

AI agents interact with Backlog.md through a native, preferred method using the Multi-Agent Communication Protocol (MCP), or via standard CLI commands for legacy agents. Backlog.md runs an MCP server that exposes tools and resources for agents.

  • Resources: These are guides that instruct the agent on the workflow, such as the Workflow Overview, Task Creation Guide, Task Execution Guide, and Task Completion Guide. This onboards the agent to the project’s process.
  • MCP Tools: These are commands the agent can execute natively, such as searching for existing tasks, viewing task details, creating new tasks, and updating them.

Benefits of “Context Engineering”

This approach of using small, atomic tasks can be described as a form of context engineering. It provides several key advantages:

  • Scoped Context: By defining how much an agent should implement in a single task, it prevents the agent from exceeding its context window.
  • Prevents Scope Creep: Agents implement only what is specified in the acceptance criteria, avoiding unwanted extra features.
  • Well-Defined Scope: Acceptance criteria clearly define what should and should not be part of the feature.
  • Easy Rollbacks: If an agent fails on a small, atomic task, it’s simple to discard the changes, adjust the specs, and restart without losing significant work.
  • Parallel Development: The use of Git allows developers to work on multiple tasks in parallel using git worktrees, provided there are no dependencies.

Interestingly, 99% of Backlog.md’s own code was written by AI agents, demonstrating the power and effectiveness of this workflow.

Share post

Stay In The Loop! Subscribe to Our Newsletter.

Get updates straight to your inbox. No spam, just useful content.

Recommended for You

The Unbearable Lightness of Agent Optimization — Alberto Romero, Jointly

The Unbearable Lightness of Agent Optimization — Alberto Romero, Jointly

This talk introduces Meta-ACE, a learned meta-optimization framework that dynamically orchestrates multiple strategies (context evolution, adaptive compute, hierarchical verification, and more) to maximize AI agent performance. The framework profiles each task to select an optimal strategy bundle, overcoming the single-dimension limitations of previous methods.

Context Engineering & Agentic Search with the CEO of Chroma

Context Engineering & Agentic Search with the CEO of Chroma

Jeff Huber, CEO of Chroma, discusses "context rot," the degradation of AI performance in large context windows, and outlines a new vision for retrieval infrastructure. He covers the evolution of search, the importance of a two-stage recall-then-precision pipeline, and the challenges of agentic memory, advocating for a shift from AI "alchemy" to reliable engineering.