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

Channel: aiDotEngineer

Published at: 2025-11-24

YouTube video id: zMXKhhwiCIc

Source: https://www.youtube.com/watch?v=zMXKhhwiCIc

Have you ever had your agent working for
almost one 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 Gavesco 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 cand 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 comban 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 criterias of tasks that are
still to be uh 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 criterias 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
to 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 the its
order. Or we can go left and right 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 ask. And the user should be
informed uh how this functionality works
by showing the button in the footer.
So let's have cloud actually implement
the task uh uh the task. But first the
task has to be created. So we tell given
this requirements to create a task.
Now clude 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 clude acts
as a developer that has been re uh just
on boarded 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 uh what we what is
there. So this is how it looks. Backlog
empty tasks are stored as markdown files
in your repository. We have a front
matter section with meta task metadata
such as task ID, title, labels and other
metadata fields. We have the description
and let's read if Claude uh actually
understood why what is the purpose of
this task.
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. So
we can confirm that cloud really
understand why we want to build this
feature. The next section of backlog
tasks is the acceptance criteria.
And here we can have really clear uh
acceptance criteria that define how the
task the feature should behave and they
should be testable and easily uh
verifiable.
This is uh 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 uh check the documentation and
internet and search also the existing
codebase 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 cloud.
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. Uh this will take some
time. Of course he has to really uh 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 uh an MCP server to
expose information instructions for the
M 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 AI 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
agents want to implement the task, what
should be done at this point? Such as
putting the task into in progress uh
status and assigning the tasks to
themsel. And the last guide is about
completing a task and uh checking the
acceptance criterias 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
their agents so that they can run
backlog commands directly and natively.
For example, one of them is searching
tasks. Before creating new task, AI
agents should search if that task
already exists.
It should 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 them.
Okay, let's continue. Now, uh hopefully
cloud 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 the second and
most important review step. This is the
moment where a senior software engineer
can really understand if the agent is
going is the in the right direction. So
it is very important at this point to
double check if everything is all right.
So now uh 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 Cloex
or Gemini or Kuso 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
means implement all of the acceptance
criterias 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.
Uh before checking um 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 task 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 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 comban board and we can immediately
spot a new command M to move. So let's
uh 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 uh 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 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 their context window and you
know exactly what will be implemented
and they don't implement extra features
that are not wanted and since you we are
using smaller atomic tasks if something
goes wrong Um 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 um if you
run unit test they should also uh check
if the acceptance criteria as are met
and it will allow this three review uh
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 the right direction and at the end
you will review the code.
You can also work on multiple tasks in
parallel using git works
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 crossplatform. 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 uh 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 co 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
andd or experiment with it, you can
visit backlog.mmd in your browser. If
you have any comments, please reach out
to me and I will be happy to help you on
board uh with backlog MD. Bye.