Backlog.md Workflow Skill

Expert guidance for managing projects with Backlog.md - a markdown-native task manager with MCP support.

Core Concepts

Tasks

• Stored as markdown files in backlog/tasks/
• Named pattern: task-<id> - <title>.md
• Support: status, priority, labels, assignees, acceptance criteria, notes, plans, dependencies

Epics (Parent-Child)

• Parent tasks group related work
• Create subtasks with -p <parent-id>
• Track epic progress via subtask completion

Dependencies

• Tasks can depend on other tasks
• Prevents starting blocked work
• Creates execution sequences
• Validated for circular references

Statuses

• "To Do": Not started
• "In Progress": Currently being worked on
• "Done": Completed

Command Reference

Task Operations

backlog task create "Title" [options]
backlog task edit <id> [options]
backlog task <id>              # View task
backlog task list [filters]    # List tasks
backlog task archive <id>      # Archive completed task

Common Options

--desc, -d     Description
--status, -s   Task status
--priority     high/medium/low
--labels, -l   Comma-separated labels
--assignee, -a @username
--ac           Acceptance criteria (repeatable)
--dep          Dependencies (task-1,task-2)
--plan         Implementation plan
--notes        Implementation notes
--append-notes Add to existing notes
-p             Parent task ID (for subtasks)

Board & Search

backlog board              # Interactive Kanban board
backlog board export       # Export to markdown
backlog search "query"     # Fuzzy search tasks
backlog overview           # Project statistics

Acceptance Criteria

--ac "Criterion"           # Add criterion
--check-ac 1               # Mark #1 complete
--uncheck-ac 2             # Mark #2 incomplete
--remove-ac 3              # Remove criterion

Workflow Patterns

Starting New Work

1. Search for existing tasks: backlog search "<keywords>"
2. If exists, update status to "In Progress"
3. If new, create task with full context
4. Set dependencies if applicable

During Work

1. Add implementation notes as you learn
2. Check acceptance criteria as completed
3. Update status appropriately
4. Create subtasks for discovered work

Completing Work

1. Verify all acceptance criteria are checked
2. Add final implementation notes
3. Move to "Done" status
4. Archive if no longer needed

Epic Planning

1. Create parent task with epic overview
2. Break into 5-10 focused subtasks
3. Establish dependencies between subtasks
4. Track progress via subtask completion

Multi-line Input (Bash/Zsh)

Use ANSI-C quoting for newlines:

backlog task edit <id> --notes $'Line 1\nLine 2\n\nParagraph 2'

MCP Integration

When MCP is available, use backlog tools directly:

• backlog.task_create - Create tasks
• backlog.task_update - Update tasks
• backlog.task_list - List tasks
• backlog.acceptance_criteria_check - Check criteria
• backlog.implementation_notes_append - Add notes
• backlog.dependencies_add - Add dependencies