backlog.md

The web UI provides several interactive features for managing your backlog without using the CLI:

• Interactive Kanban Board: Drag-and-drop tasks between different statuses.
• Task Management: Create, edit, and archive tasks using modal dialogs.
• Search & Filter: Real-time filtering of tasks by status, assignee, or labels.
• Markdown Support: View and edit task descriptions with rich markdown rendering.
• Dark Mode: Built-in theme support via Tailwind CSS.
• Responsive Design: The UI is mobile-friendly and works across different devices.

Backlog.md is a Markdown-native task manager where task state lives in human-readable Markdown files.

Key architectural principles:

• Durable Substrate: Markdown is the primary storage format. Files must remain understandable with ordinary tools and useful without a hosted service.
• Semantic Mutations: Product commands perform mutations to ensure metadata and relationships stay consistent.
• Local-first Ownership: Users own their files; no account, hosted backend, or telemetry is required for the core workflow.
• Deterministic Serialization: Ordering and serialization are deterministic so that Git diffs explain meaningful changes.
• Git Integration: While Git is optional, it is used to provide reviewable evidence and history.

To manually test the Zsh completion script for the backlog CLI, load the completion file into your current session and then use the <TAB> key to trigger completions for various command levels.

# 1. Load the completion
source completions/_backlog

# 2. Test completions
backlog <TAB>
backlog task <TAB>
backlog task create --<TAB>

The Backlog.md MCP implementation provides a stdio Model Context Protocol (MCP) surface, allowing local AI agents to interact with your backlog using tools for tasks, milestones, Definition of Done defaults, and documents.

You can start the server either by running it directly from the repository using bun or by using the globally installed backlog CLI.

# Run the stdio server from the repo
bun run cli mcp start

# Or via the globally installed CLI
backlog mcp start

The Backlog CLI is available for global installation via npm. This installs the Node.js distribution version of the tool.

npm install -g backlog.md

When using an IDE that launches the Model Context Protocol (MCP) with an incorrect process working directory, you can force the correct project root using the --cwd flag with the backlog mcp start command. This flag takes precedence over environment variables.

Use this when the MCP server cannot automatically find your Backlog project due to the host environment's current working directory.

backlog mcp start --cwd <path>

When using the task-finalization workflow, agents are explicitly instructed to reject AC (Acceptance Criteria) checks based solely on:

• Code presence (checking if a function exists in a file).
• grep output (checking if a string exists in the codebase).
• Intent (assuming the code works because it looks correct).

Instead, agents must use objective behavior evidence. For web-based tasks, this typically involves running a Node.js/jsdom audit or a headless browser test to verify rendered elements, user interactions (like clicks), and logic (like win/draw detection).