Backlog.md

Table of content

project management tools have been overthinking the problem for decades. Backlog.md proves the simplest answer was hiding in plain sight: just use markdown files in your git repo.

what it is

Backlog.md (4,605 ★) is a markdown-based project collaboration system designed for both humans and AI agents. everything lives in .md files: tasks, issues, agent instructions, project state. no external services, no proprietary formats, no vendor lock-in.

the entire workflow is git-native. create a task? markdown file. assign it to an agent? markdown frontmatter. check status? grep your repo. collaborate? pull request.

it’s project management that works the way developers already work.

why it matters

every project management tool tries to solve collaboration by adding layers. Jira, Linear, Asana — they all bolt on complexity. integrations, webhooks, custom fields, automation rules. the more features they add, the more friction you get.

Backlog.md goes the opposite direction: remove layers until only the essential structure remains. tasks are files. status is git history. collaboration is merge conflicts (but readable ones).

this isn’t just another markdown task manager. it’s infrastructure. the same .md files humans read are the API surface for AI agents. no translation layer, no sync issues, no “export to markdown” buttons. the source of truth is markdown.

first spotted in signals — 2026-02-09 , where it crystallized the pattern: .md files aren’t documentation anymore. they’re the protocol layer between humans and agents.

how it works

structure is dead simple:

project/
├── backlog/
│   ├── feature-x.md
│   ├── bug-auth.md
│   └── refactor-api.md
├── in-progress/
│   └── task-123.md
├── done/
│   └── completed-task.md
└── agents/
    └── instructions.md

each task is a markdown file with YAML frontmatter:

---
title: implement auth flow
assignee: @agent-backend
priority: high
labels: [auth, security]
---

## context

users need to log in before accessing dashboard.

## acceptance criteria

- [ ] JWT token generation
- [ ] refresh token rotation
- [ ] logout endpoint

## notes

use existing session service. coordinate with frontend team.

AI agents read these files directly. no parsing layer, no API wrapper. they see the same thing you see. update a task? commit it. agent makes progress? commit shows exactly what changed.

the workflow loop:

  1. human writes task in markdown
  2. commits to repo
  3. agent reads task from file
  4. agent works, updates file with progress
  5. commits changes
  6. human reviews via git diff
  7. merge or iterate

version control becomes the collaboration layer. you get history, branching, code review, and rollback for free. because it’s just git.

why markdown won

not YAML. not JSON. not TOML. markdown.

the reason: it’s the only format that’s truly bidirectional. humans can write it without thinking. agents can parse it without ambiguity. you can read a markdown task list in your editor, in GitHub’s UI, in your terminal with cat, or in an AI agent’s context window.

no other format has this property. JSON is machine-first. plain text is too unstructured. markdown hit the exact sweet spot: enough structure to parse, enough flexibility to stay human.

Backlog.md proves you don’t need a database to manage projects. you don’t need a web UI. you don’t need real-time sync. you just need well-structured files in a git repo.

the stack is: markdown files → git → your existing tools. that’s it.

install

# clone the template
git clone https://github.com/MrLesk/Backlog.md.git my-project-backlog
cd my-project-backlog

# or add to existing repo
mkdir backlog in-progress done agents
echo "# project backlog" > backlog/README.md

no installation required. it’s markdown files. use whatever editor you already have.

fits the self.md thesis

the self.md thesis: your repo is your operating system. markdown files are the API surface. tools that speak markdown win.

Backlog.md nails this. it doesn’t try to be a platform. it’s infrastructure that fits into your existing workflow. human-readable, agent-parseable, git-native.

compare to traditional project management:

Backlog.md: the source of truth lives where your code lives. one repo, one history, one workflow.

this is what “personal AI OS” actually looks like in practice. not a monolithic app. just well-structured markdown files that both humans and agents can work with.