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

task42 - Title.md

Add authentication.md

task-42.md

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

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

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

backlog task edit 42 -s "In Progress"

backlog task edit 42 -a @sara

backlog task edit 42 -d "New description"

backlog task edit 42 -t "New Title"

backlog task edit 42 -l backend,api

backlog task edit 42 --priority high

Acceptance Criteria (AC)

backlog task edit 42 --ac "New criterion"

backlog task edit 42 --ac "First" --ac "Second"

backlog task edit 42 --check-ac 1

backlog task edit 42 --check-ac 1 --check-ac 2

backlog task edit 42 --uncheck-ac 2

backlog task edit 42 --remove-ac 3

backlog task edit 42 --check-ac 1 --uncheck-ac 2 --ac "New"

Implementation Planning & Notes

backlog task edit 42 --plan $'1. Step 1\n2. Step 2'

backlog task edit 42 --notes "Implementation details"

backlog task edit 42 --append-notes "Additional note"

Searching & Filtering

backlog search "auth" --plain

backlog task list -s "To Do" --plain

backlog task list -a @sara --plain

backlog search "api" --type task --plain

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

backlog task 42 --plain

backlog task edit 42 --check-ac 1

- [ ]

- [x]

backlog task edit 42 --notes "..."

backlog task edit 42 -s Done

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