Backlog Quick Reference

Backlog.md CLI Quick Reference Skill

🚨 CRITICAL: File Naming Convention

Sacred Pattern: task-{id} - {title}.md

Examples

✅ task-1 - Initial setup.md ✅ task-42 - Add authentication.md ✅ task-137 - Refactor API endpoints.md

❌ task-42-Add authentication.md (missing spaces) ❌ task42 - Title.md (missing hyphen) ❌ Add authentication.md (missing task ID) ❌ task-42.md (missing title)

Why This Matters

• CLI parses filenames to extract task ID and title
• Git tracking relies on consistent naming
• Metadata synchronization depends on format
• Breaking this format breaks Backlog.md functionality

Golden Rule

NEVER manually create, rename, or edit task files. ALWAYS use backlog task create and backlog task edit.

Overview

Backlog.md is a comprehensive CLI tool for managing project tasks, acceptance criteria, and documentation. All task modifications MUST use CLI commands.

Reference Guide: For complete documentation, see docs/backlog-md-cli-usage.md in this plugin

Quick Start

Viewing Tasks

backlog task list --plain              # List all tasks
backlog task 42 --plain                # View specific task
backlog search "keyword" --plain       # Search for tasks

Creating Tasks

# Basic task
backlog task create "Task title" -d "Description"

# With acceptance criteria
backlog task create "Title" -d "Desc" --ac "AC 1" --ac "AC 2"

# With all options
backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l backend,api --priority high

Working on a Task

# Start working on a task
backlog task edit 42 -s "In Progress" -a @myself

# Add implementation plan
backlog task edit 42 --plan $'1. Research\n2. Implement\n3. Test'

# Mark acceptance criteria complete (supports multiple)
backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3

# Add implementation notes
backlog task edit 42 --notes "Implemented using pattern X because Y"

# Mark as done
backlog task edit 42 -s Done

Essential Commands

Editing Tasks

Acceptance Criteria (AC)

Implementation Planning & Notes

Searching & Filtering

Multi-line Input Tips

For descriptions, plans, and notes with multiple lines, use Bash ANSI-C quoting:

# Example with newlines
backlog task edit 42 --plan $'1. Research\n2. Implement\n3. Test'

# Multi-paragraph notes
backlog task edit 42 --notes $'Implemented feature X\n\nAdded comprehensive tests\nUpdated documentation'

Workflow Example

# 1. Create a task
backlog task create "Add user authentication" \
  -d "Implement login/logout functionality" \
  --ac "Login with valid credentials" \
  --ac "Session persists across page reloads" \
  --ac "Logout clears session"

# 2. Start working (assuming task ID is 42)
backlog task edit 42 -s "In Progress" -a @myself

# 3. Add implementation plan
backlog task edit 42 --plan $'1. Research auth patterns\n2. Implement login endpoint\n3. Add session management\n4. Write tests'

# 4. During implementation, check off ACs as you complete them
backlog task edit 42 --check-ac 1

# 5. When done, add implementation notes
backlog task edit 42 --notes "Implemented JWT-based auth with HTTP-only cookies for security"

# 6. Mark all remaining ACs complete
backlog task edit 42 --check-ac 2 --check-ac 3

# 7. Mark task as done
backlog task edit 42 -s Done

Definition of Done Checklist

A task is Done only when ALL of these are complete:

• All acceptance criteria checked via CLI (--check-ac)
• Implementation notes added via CLI (--notes)
• Status set to "Done" via CLI (-s Done)
• Tests pass and linting checks pass
• Documentation updated if needed
• Code reviewed
• No regressions detected

Golden Rules

1. Never edit task files directly - Use CLI commands only
2. Always use --plain flag when listing/viewing tasks
3. Mark ACs as you complete them - Don't wait until the end
4. Share implementation plans with user before coding
5. Use newlines in descriptions/plans/notes for readability
6. Respect the naming pattern - task-{id} - {title}.md

Task Status Flow

• New task → "To Do"
• Starting work → "In Progress" (+ assign yourself)
• Work complete → "Done" (all ACs checked, notes added)

Acceptance Criteria Strategy

• Outcome-focused - What does the user/system do, not implementation details
• Testable - Can be objectively verified
• Independent - Each AC is a unit of work
• Complete - Together they define the full task scope

Good ACs (outcome-focused)

• "User can log in with valid credentials"
• "System returns 404 for non-existent resources"

Bad ACs (implementation-focused)

• "Add login() function to auth.ts"
• "Use bcrypt for password hashing"

Notes Format (PR Description Style)

- Outcome: What was implemented
- Implementation: How it was done and why
- Testing: What was tested
- Follow-up: Any next steps or known issues

Common Patterns

DO vs DON'T

Full Documentation

For complete documentation including all options and advanced features:

# Read comprehensive guide
cat docs/backlog-md-cli-usage.md

# CLI help
backlog --help