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

What happens when an agent works for almost an hour before you discover it has misunderstood the feature? Or when it exhausts its context window halfway through something important? Alex Gavrilescu’s response is to divide large features into smaller Markdown tasks. Backlog.md makes those tasks a shared project-management surface for humans and AI agents.

The starting point is a Kanban board inside the terminal. Open a task and you can inspect its description and acceptance criteria; move through the In Progress and Done columns and you can see completed criteria and implementation notes. The board already makes work visible, but it lacks an interaction Gavrilescu wants: moving tasks between status columns and reordering them within a column. That missing feature becomes the demonstration’s task.

Before asking Claude Code to build move mode, Gavrilescu specifies its behavior. Clear requirements matter for an agent for the same reason they matter for a human developer: implementation cannot resolve an intention that was never made explicit.

The footer must expose the command and explain the interaction. These requirements distinguish selecting a task, changing its proposed position, and committing or canceling that change—behaviors that a vague request to make the board movable would leave unresolved.

The first request is to create a task from those requirements, not to implement the feature. Claude initially has to learn how the project works, much like a newly onboarded developer. It reads the Backlog information and task-creation guidance, then creates the task. Completion at this point means the task record exists; the feature is still unimplemented.

Backlog tasks are Markdown files in the repository. Front matter holds metadata such as the task ID, title, and labels. The body explains the purpose: keyboard navigation should let users reorganize the terminal board without issuing CLI commands or editing files directly. The acceptance criteria then turn that purpose into testable behavior. A compact Markdown contract for the demonstrated interaction would look like this:

## Description

Add move mode to the terminal Kanban board so users can reorder
and change the status of tasks without CLI commands or file edits.

## Acceptance Criteria

- [ ] M enters move mode and highlights the selected task.
- [ ] Up and Down reorder the task within its current column.
- [ ] Left and Right move the task between status columns.
- [ ] M or Enter commits the move.
- [ ] Esc cancels the move.
- [ ] The footer explains the move command and controls.

The first review checks intent. Read the description and criteria before code is written: do they describe the feature you meant, and can each criterion be verified? This is the earliest opportunity to catch a misunderstanding cheaply.

The next request is an implementation plan. The agent must understand the description and acceptance criteria, inspect the existing codebase, and consult project documentation or external documentation where needed. The resulting plan should explain where the feature belongs and how to implement it.

Gavrilescu explicitly asks Claude to create that plan according to the Backlog.md workflow for the newly created task. While it works, the useful investigation is concrete: which files need edits, what existing behavior they contain, and what documentation constrains those changes.

Backlog.md’s MCP server supplies both instructions and operations. Its MCP resources provide workflow context, starting with an overview of what Backlog is and when to use it. Resource inclusion is controlled by the host application; exposing the instructions does not by itself guarantee that every client reads them.

The overview points agents toward guides for each stage:

The guides give task status a procedural meaning. Marking work Done follows checking the requirements, rather than merely reaching the end of a coding response.

MCP tools provide the corresponding operations. Before creating a task, the agent should search for an existing one. It can then view task details, create or update tasks, update acceptance criteria, and mark completed work Done. Resources explain how to work; tools let the agent carry out that workflow through native task operations.

Claude returns an architecture overview, implementation steps, and a list of files to modify with explanations of the changes. The second review checks direction. Gavrilescu calls this the most important checkpoint: a senior engineer can assess whether the proposed approach fits the project before the agent commits effort to implementation. The presentation moves directly onward rather than demonstrating a detailed plan review.

Execution starts from the accumulated task context: description, acceptance criteria, and plan. Gavrilescu names Claude Code, Gemini, and Cursor as agents that can work with Backlog.md. Their assignment is to implement all acceptance criteria and mark the task Done only when the definition of done is fulfilled. He then asks Claude to implement the feature and pauses the recording while it works.

A human can create these records directly with Backlog’s CLI, but the demonstration uses an agent to translate a feature description into the required task sections. Once that context is stored, the execution request can be short: ask Claude to implement task 316. The task ID points to the specification instead of requiring the human to repeat it in the conversation.

Back in the terminal, the footer now advertises m to move. Gavrilescu enters move mode, sees the task highlighted, reorders it vertically, and moves it across a status column. He cancels this first move because he does not want to change that task.

Next he selects the newly implemented task, 316. To model what would happen if its implementation were incomplete, he moves it back to In Progress. The board shows the task in that destination column. This is a demonstration of reopening work, not a report that he discovered a defect. Gavrilescu describes the specification-driven implementation as taking a few minutes, but the recording pauses during execution and does not establish elapsed runtime.

Repository Markdown tasks make context engineering a practical scoping decision: how much should the agent implement in one task? Smaller, atomic tasks aim to keep the assignment within the available context and make the expected change explicit. If an attempt goes wrong, the recovery path is bounded too: roll back, revise the specification, description, or acceptance criteria, and ask the agent to start again from the implementation plan.

Acceptance criteria define what belongs in the feature and what does not. Unit tests should check those same criteria, connecting the written contract to verification rather than allowing the task and tests to describe different outcomes.

The workflow therefore has three review checkpoints, each answering a different question:

1. Review the task: Do the description and acceptance criteria capture the intended feature?
2. Review the plan: Is the agent proposing the right implementation direction?
3. Review the code: Does the resulting change satisfy the task?

These checkpoints give the human opportunities to correct the work before and after implementation, instead of waiting until the agent’s entire attempt is finished.

Independent tasks can run in parallel using Git worktrees. The qualification matters: Gavrilescu recommends this when tasks have no dependencies. Separate working directories provide room for concurrent work; they do not remove dependencies between features. Backlog.md itself is an open-source, MIT-licensed CLI with both terminal and web interfaces.

In the demonstrated workflow, MCP is the preferred native interface for agents, with CLI commands available for legacy agents. The current README instead recommends CLI instructions while retaining optional MCP support. Gavrilescu also describes Backlog as cross-platform, with support for the major operating systems.

The task store lives in the team’s Git repository, without requiring a separate task-service API, database, or account. Gavrilescu says Backlog checks task status even when another branch contains an update. That should be understood as cross-branch checking rather than unconditional team synchronization: the current configuration makes checking configurable, filters active branches by age, and reads only local branches when remote operations are disabled. Automatic commits are disabled by default.

Gavrilescu reports that AI agents wrote 99% of Backlog’s code; he personally wrote the instructions and the first three tasks. He supplies no counting method for that percentage. The project is thus also his example of using carefully written instructions and initial tasks to guide agent development of the workflow tool itself.

To experiment with the workflow, Gavrilescu directs viewers to Backlog.md and invites comments or requests for onboarding help. The repository is the starting point for trying the same progression: describe a feature, inspect the task, review its plan, and then let the agent implement it.