backlog-workflow

yebot's avatarfrom yebot

Expert knowledge for working with Backlog.md task management. Use when managing tasks, organizing epics, handling dependencies, or tracking project progress. Automatically applies Backlog.md best practices.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 15, 2025

When & Why to Use This Skill

This Claude skill provides expert guidance and automated tools for managing projects using Backlog.md, a markdown-native task manager. It streamlines task creation, epic organization, and dependency tracking directly within your development environment, ensuring project progress is documented and managed according to best practices for efficient project lifecycle management.

Use Cases

  • Epic Planning: Break down large-scale projects into structured parent-child tasks with clear execution sequences and progress tracking.
  • Dependency Management: Define and validate task dependencies to prevent starting blocked work and ensure a logical development flow.
  • Automated Task Tracking: Update implementation notes, check off acceptance criteria, and transition task statuses using simple CLI-style commands or MCP tools.
  • Project Visualization: Generate interactive Kanban boards and comprehensive project overviews to maintain visibility on team velocity and task distribution.
namebacklog-workflow
descriptionExpert knowledge for working with Backlog.md task management. Use when managing tasks, organizing epics, handling dependencies, or tracking project progress. Automatically applies Backlog.md best practices.
allowed-toolsRead, Bash, Grep, Glob

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)
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