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

Have you ever had your agent working for almost 1 hour only to understand that he went in the wrong direction, or in the middle of something very important he ran out of context window? Me too. That's why in the last months I developed a workflow that consists in dividing a big feature into smaller Markdown tasks.

Hi, I'm Alex Gavrilescu, and I'm going to present Backlog.md, a tool for project management for AI agents and humans. Okay, let's start. So, have you ever seen a terminal Kanban board? Well, when I started working on Backlog.md, I couldn't find any, so I had to build it myself.

We have a full Kanban board directly in your terminal, and here we can see our tasks for the current project, and we can actually see the details of the task directly in our terminal. We can see the description and acceptance criteria of tasks that are still to be developed.

We have the "In Progress" and the "Done" columns as well, where we can see what has been implemented. In this case, we can see the acceptance criteria were implemented, and someone left some implementation notes. But one of the features I always wanted to have in Backlog.md is the ability to move tasks between status columns, and to reorder tasks within the same column.

So, let's build it with Cloud Code.

Before we can build it with Cloud Code, we need to have clear requirements. This is important for humans, but also for AI agents. So, first thing to do is we want to press M to toggle the move mode.

Then the current task will be highlighted, and we know which task is going to be moved. We can use the arrow keys up and down to move the task within the same column and change its order. Or we can go left andright, and this will change the status of the task.

If we press M or Enter, we will commit this move, and if we want to cancel, we will press Esc. And the user should be informed how this functionality works by showing the button in the footer.

So, let's have Claude actually implement the task, but first the task has to be created. So we tell Claude, "Given these requirements," to create a task. Now, Claude, the first thing that it will do is going to search for existing tasks.

Actually, the first thing that he does, he needs to understand how Backlog works and what is Backlog, because Claude acts as a developer that has been just onboarded on our project and needs to understand how our project works.

So he first reads about Backlog, and then he reads about how to create tasks correctly. Afterwards, he creates the task. We can see here the task has been completed. And now let's check what is there. So, this is how it looks.

Backlog.md tasks are stored as Markdown files in your repository. We have a front matter section with task metadata, such as task ID, title, labels, and other metadata fields. We have the description, and let's read if Claude actually understood why.

What is the purpose of this task? Add a move mode feature in the TUI Kanban 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.

So we can confirm that Claude really understands why we want to build this feature. The next section of Backlog tasks is the acceptance criteria. And here we can have really clear acceptance criteria that define how the task the feature should behave, and they should be testable and easily verifiable.

This is the first review point. This is the moment where you can actually understand if the AI agent has understood your intent and will do a good task.

The next step is the implementation plan. So we want the AI agent to come up with an implementation plan because he must understand really well the description and the acceptance criteria. It can check the documentation and internet, and search also the existing code base to understand where to put this feature.

And then at the end, it will write an implementation plan. So let's have this done actually by Claude. So we give him the instruction to create an implementation plan according to Backlog.md workflow for the task that he just it just created.

So we wait a bit. This will take some time. Of course, he has to really find what files have to be edited, maybe look up on the internet for some documentation and existing documentation in our project. In the meantime, let's explain how this works under the hood.

So, Backlog.md uses an MCP server to expose information instructions for the AI agents, but also tools. The most important part is the resources. So this is a special feature of MCP that Backlog.md uses to instruct the agents how to use Backlog.md.

The first resource is the workflow overview. Here, we're telling the agents what is Backlog and what can be used for. And also, this overview will present the next resources that are available, which are the task creation guide, letting the AI agents know how to create tasks and what fields are required and which ones are optional.

The task execution guide, when an AI agent wants to implement a task, what should be done at this point, such as putting the task into In Progress status and assigning the tasks to themselves. And the last guide is about completing a task and checking the acceptance criteria if they are all actually implemented correctly, and checking all of the other requirements for the definition of done that we specified.

And then, how can agents use Backlog? Well, via MCP tools. So Backlog.md server will expose certain tools for the AI agents so that they can run Backlog commands directly and natively. For example, one of them is searching tasks.

Before creating a new task, AI agents should search if that task already exists. They should be able to view the details of these tasks. They should be able to create tasks and update tasks and update their acceptance criteria and put them into Done.

Okay, let's continue. Now, hopefully Claude finished creating the implementation plan, so let's check what we have. So we have an architecture overview, we have implementation steps, and then he actually starts enumerating which files should be touched and modified, and the how.

And here we have the second and most important review step. This is the moment where a senior software engineer can really understand if the agent is going in theright direction. So it is very important at this point to double-check if everything is allright.

So now, for the purpose of this presentation, let's go directly to the implementation part. So for the execution, we want to have the agent write the code for us. So Claude, Codex, or Gemini, or Cursor, they can all work with Backlog.md.

And they should learn about the task, the description, the acceptance criteria, and the plan. And what does develop the feature means? It means implement all of the acceptance criteria and putting the task into Done when the definition of Done is fulfilled.

So let's have Claude actually implement it.

This is going to take a while, so we're going to pause this video and come back when Claude has finished. And we're done. Before checking what Claude has implemented, let's have a quick review of the Backlog workflow. So as a human, I want to create tasks.

I want to develop features in my project. So normally, I could create tasks directly using Backlog CLI commands, but it is more convenient if we ask our AI agent to do it for us. So we can have a human description about what we want to implement, and the AI agent will run the Backlog commands to create the task and to fill the sections that are needed.

And when the task is created, we can tell an agent something as simple as, "Hey Claude, can you please implement task 316?" And he will do it. So let's see what Claude has implemented. So we have our terminal here with our new Kanban board, and we can immediately spot a new command, M to move.

So let's press this button. You can see the task has been highlighted, and I can go up and down, and the task is being moved. And we can also, hopefully, yes, go to the new status column. So we can commit or we can cancel.

Let's cancel because we don't want to move this task. But for example, let's try the task that has been just implemented. So this is the task 316. Let's say there was a problem and not everything has been implemented correctly.

Let's move it back in progress.

And it works. It has been successfully moved to In Progress column. So this is an example of how you can use Backlog.md with your favorite AI agent, and you can have a task implemented correctly according to your specs in a few minutes.

But why does this work so well? Having Markdown tasks stored in your repo allows you to do a sort of context engineering, which means you can define how much an AI agent should implement within a single task so that he doesn't run out of the context window, and you know exactly what will be implemented, and they don't implement extra features that are not wanted.

And since we are using smaller atomic tasks, if something goes wrong with each of these with any of these tasks, you can roll back, change the specs, the acceptance criteria, the description, and ask the AI agent to start again from the implementation plan.

The scope is well defined. So you can really define with using the acceptance criteria what should be part of this feature and what should be not part of this feature. And the tests, if you run unit tests, they should also check if the acceptance criteria are met.

And it will allow this trivia review process that I just showed to you. The first review checkpoint is after the task is created. You can check the description and the acceptance criteria if the agents understood your intent. Then you can review the implementation plan.

You can see if the agent is going into theright direction. And at the end, you will review the code.

You can also work on multiple tasks in parallel using Git work trees, given that there are no dependencies. So what is Backlog? It's an open source MIT CLI tool. It has a terminal user interface, but also web interface.

AI agents can interact via CLI commands or via MCP. MCP is the preferred native way, but we also support CLI commands for legacy AI agents. It is cross-platform. It works on most famous operating systems. And you don't need any extra APIs or tools or databases or accounts.

As long as you host all of the tasks on your Git repository, you can share them with your team, and all of the tasks are in sync, which means that Backlog checks the status of a task even if this task has been updated on another branch.

And most important part, Backlog code has been written 99% by AI agents. The only part of the project that I written myself were the instructions and the first three tasks.

Thank you very much for your attention. If you want to know more about Backlog.md or experiment with it, you can visit backlog.md in your browser. If you have any comments, please reach out to me, and I will be happy to help you on board with Backlog.md.

Bye.