Backlog.md

Expert assistance with Backlog.md CLI project management tool.

Overview

Backlog.md is a CLI-based project management tool that uses markdown files to track tasks, documentation, and decisions. All operations go through the backlog CLI command.

Key Principle: NEVER edit task files directly. Always use CLI commands.

Quick Start

List tasks

backlog task list --plain

View task details

backlog task 42 --plain

Create task

backlog task create "Task title" -d "Description" --ac "Acceptance criterion"

Edit task

backlog task edit 42 -s "In Progress" -a @me

Search

backlog search "keyword" --plain

Task Creation

Basic Task Creation

Simple task

backlog task create "Implement user login"

With description

backlog task create "Implement user login" -d "Add authentication flow"

With acceptance criteria

backlog task create "Implement user login"
--ac "User can login with email and password"
--ac "Invalid credentials show error message"

Complete task creation

backlog task create "Implement user login"
-d "Add authentication flow with session management"
--ac "User can login with valid credentials"
--ac "Session persists across page refreshes"
-s "To Do"
-a @developer
-l backend,auth
--priority high

Advanced Creation

Create draft task

backlog task create "Research options" --draft

Create subtask

backlog task create "Implement feature component" -p 42

With dependencies

backlog task create "Deploy to production" --dep task-40 --dep task-41

With multiple labels

backlog task create "Fix bug" -l bug,urgent,frontend

Task Modification

Status Management

Change status

backlog task edit 42 -s "In Progress" backlog task edit 42 -s "Done" backlog task edit 42 -s "Blocked"

Common workflow: start work on task

backlog task edit 42 -s "In Progress" -a @me

Basic Fields

Update title

backlog task edit 42 -t "New title"

Update description (with newlines)

backlog task edit 42 -d $'Multi-line\ndescription\nhere'

Assign task

backlog task edit 42 -a @username

Add/update labels

backlog task edit 42 -l backend,api,v2

Set priority

backlog task edit 42 --priority high backlog task edit 42 --priority medium backlog task edit 42 --priority low

Acceptance Criteria Management

IMPORTANT: Each flag accepts multiple values

Add new criteria (multiple flags supported)

backlog task edit 42 --ac "User can login" --ac "Session persists"

Check criteria by index (multiple flags supported)

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

Uncheck criteria

backlog task edit 42 --uncheck-ac 2

Remove criteria (processed high-to-low)

backlog task edit 42 --remove-ac 3 --remove-ac 2

Mixed operations in one command

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

Note:

• ✅ Use multiple flags: --check-ac 1 --check-ac 2

• ❌ Don't use commas: --check-ac 1,2,3

• ❌ Don't use ranges: --check-ac 1-3

Implementation Plan & Notes

Add implementation plan (with newlines using ANSI-C quoting)

backlog task edit 42 --plan $'1. Research codebase\n2. Implement solution\n3. Write tests\n4. Update docs'

POSIX portable (using printf)

backlog task edit 42 --plan "$(printf '1. Step one\n2. Step two')"

Add implementation notes (replaces existing)

backlog task edit 42 --notes $'Implemented using strategy pattern\nUpdated all tests\nReady for review'

Append to existing notes

backlog task edit 42 --append-notes $'- Fixed edge case\n- Added validation'

Format notes as PR description (best practice)

backlog task edit 42 --notes $'## Changes\n- Implemented X\n- Fixed Y\n\n## Testing\n- Added unit tests\n- Manual testing complete'

Dependencies

Add dependencies

backlog task edit 42 --dep task-1 --dep task-2

Remove dependencies (edit task file or recreate without)

Viewing Tasks

List Tasks

List all tasks (always use --plain for AI-readable output)

backlog task list --plain

Filter by status

backlog task list -s "To Do" --plain backlog task list -s "In Progress" --plain backlog task list -s "Done" --plain

Filter by assignee

backlog task list -a @username --plain backlog task list -a @me --plain

Filter by tag

backlog task list --tag backend --plain backlog task list --tag bug --plain

Combined filters

backlog task list -s "In Progress" -a @me --plain

View Task Details

View single task (always use --plain)

backlog task 42 --plain

View in browser (if supported)

backlog task 42 --web

Search

Search across all content (uses fuzzy matching)

backlog search "authentication" --plain

Search only tasks

backlog search "login" --type task --plain

Search with filters

backlog search "api" --status "To Do" --plain backlog search "bug" --priority high --plain

Search in specific fields

backlog search "database" --in title --plain

Task Workflow

Complete Task Lifecycle

1. Create task

backlog task create "Implement feature X"
-d "Add new feature to handle Y"
--ac "Feature works as expected"
--ac "Tests are passing"
--ac "Documentation is updated"

2. Start work: assign and change status

backlog task edit 42 -s "In Progress" -a @me

3. Add implementation plan

backlog task edit 42 --plan $'1. Research existing code\n2. Implement core logic\n3. Add tests\n4. Update docs'

4. Work on task (write code, test, etc.)

5. Mark acceptance criteria as complete

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

6. Add implementation notes (PR description)

backlog task edit 42 --notes $'## Changes\n- Implemented feature X using approach Y\n- Added comprehensive tests\n\n## Testing\n- Unit tests pass\n- Integration tests pass\n- Manual testing complete'

7. Mark task as done

backlog task edit 42 -s Done

Starting a Task (Critical Steps)

ALWAYS do these steps when starting a task:

1. Set status to In Progress

2. Assign to yourself

backlog task edit 42 -s "In Progress" -a @me

3. Review the task requirements

backlog task 42 --plain

4. Create implementation plan

backlog task edit 42 --plan $'1. Analyze requirements\n2. Design solution\n3. Implement\n4. Test\n5. Document'

Board & Visualization

View Kanban board in terminal

backlog board

Open web UI

backlog browser

Export board snapshot

backlog board --export board-snapshot.md

Generate report

backlog report --output report.md

Task Operations

Archive & Promote

Archive completed task

backlog task archive 42

Demote task to draft

backlog task demote 42

Promote draft to task (gets new ID)

backlog task promote draft-5

Task History

View task history (if supported)

backlog task history 42

View changes

backlog task diff 42

Documentation & Decisions

Documents

Create document

backlog doc create "API Documentation"

List documents

backlog doc list --plain

Edit document

backlog doc edit 1 --content "Updated content"

Architectural Decisions

Create decision record

backlog decision create "Use PostgreSQL for data storage"

List decisions

backlog decision list --plain

View decision

backlog decision 1 --plain

Best Practices

Writing Good Tasks

Title: Clear, concise, action-oriented

✅ Good

backlog task create "Implement user authentication" backlog task create "Fix memory leak in image processor"

❌ Bad

backlog task create "Users" backlog task create "There's a problem with the app"

Description: Explain the "why" and context

backlog task create "Add rate limiting to API"
-d "Current API has no rate limiting, causing server overload during peak hours. Need to implement per-user rate limiting to prevent abuse."

Acceptance Criteria: Focus on outcomes, not implementation

✅ Good - Testable outcomes

--ac "API rejects requests after 100 requests per minute per user" --ac "User receives clear error message when rate limited" --ac "Rate limit resets after 60 seconds"

❌ Bad - Implementation details

--ac "Add a rate limiter middleware" --ac "Use Redis for tracking"

Task Organization

Use Labels Effectively

Organize by type, area, and priority

backlog task create "Fix login bug" -l bug,urgent,auth backlog task create "Optimize queries" -l enhancement,backend,performance backlog task create "Update docs" -l documentation,frontend

Use Tags for Metadata

Tags for filtering and organization

--tag "sprint:23" --tag "epic:user-management" --tag "team:backend"

Task Breakdown

Atomic Tasks: Each task should be independently deliverable

✅ Good - One PR per task

backlog task create "Add login endpoint" backlog task create "Add logout endpoint" backlog task create "Add session refresh endpoint"

❌ Bad - Too large for one PR

backlog task create "Implement entire authentication system"

Avoid Future Dependencies: Never reference tasks that don't exist yet

✅ Good - Reference existing tasks

backlog task create "Deploy auth API" --dep task-40 --dep task-41

❌ Bad - Reference future tasks

backlog task create "Add feature A" -d "This will be used by future tasks"

Implementation Notes

Format as PR Description: Make notes ready for GitHub

backlog task edit 42 --notes $'## Summary

• Implemented user authentication with JWT
• Added password hashing with bcrypt
• Created login/logout endpoints

Changes

• Added auth middleware
• Updated user model
• Added auth routes

Testing

• Unit tests for auth functions
• Integration tests for endpoints
• Manual testing with Postman

Breaking Changes

None

Follow-up

• Add refresh token rotation
• Implement rate limiting'

Progressive Notes: Append as you work

As you make progress

backlog task edit 42 --append-notes "- Implemented core auth logic" backlog task edit 42 --append-notes "- Added tests" backlog task edit 42 --append-notes "- Updated documentation"

Definition of Done

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

Via CLI:

• ✅ All acceptance criteria checked: --check-ac 1 --check-ac 2 ...

• ✅ Implementation notes added: --notes "..."

• ✅ Status set to Done: -s Done

Via Code/Testing: 4. ✅ Tests pass 5. ✅ Documentation updated 6. ✅ Code reviewed 7. ✅ No regressions

Never mark task as Done without completing ALL items

Common Patterns

Daily Workflow

Morning: Check your tasks

backlog task list -a @me -s "In Progress" --plain

Start working on next task

backlog task edit 42 -s "In Progress" -a @me backlog task 42 --plain # Read requirements

Add plan

backlog task edit 42 --plan $'1. Analyze\n2. Implement\n3. Test'

As you work, check off AC

backlog task edit 42 --check-ac 1

... continue working ...

backlog task edit 42 --check-ac 2

End of day: Add notes

backlog task edit 42 --append-notes "- Completed X, Y pending"

Sprint Planning

Review backlog

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

Tag tasks for sprint

backlog task edit 42 --tag "sprint:23" backlog task edit 43 --tag "sprint:23"

Assign tasks

backlog task edit 42 -a @developer1 backlog task edit 43 -a @developer2

View sprint board

backlog board

Bug Fix Workflow

Create bug task

backlog task create "Fix login timeout issue"
-d "Users report login times out after 30 seconds on slow connections"
--ac "Login works on slow connections (tested with throttling)"
--ac "Timeout increased to 60 seconds"
--ac "User sees loading indicator during login"
-l bug,urgent,auth
--priority high

Start work

backlog task edit 42 -s "In Progress" -a @me

Implement fix and add notes

backlog task edit 42 --notes $'## Root Cause Login timeout was set to 30s, causing issues on slow connections.

Fix

• Increased timeout to 60s
• Added exponential backoff for retries
• Improved loading indicator visibility

Testing

• Tested with Chrome network throttling (Slow 3G)
• Verified timeout works correctly
• All existing auth tests pass'

Complete

backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 backlog task edit 42 -s Done

Troubleshooting

Task Not Found

List all tasks to find ID

backlog task list --plain

Search for task

backlog search "keyword" --type task --plain

Acceptance Criteria Issues

View task to see AC numbers

backlog task 42 --plain

AC numbering starts at 1

backlog task edit 42 --check-ac 1 # First AC

Check multiple at once

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

Metadata Out of Sync

Re-edit via CLI to fix

backlog task edit 42 -s "In Progress"

If persistent, check file permissions

ls -la backlog/tasks/

Multiline Input

Use ANSI-C quoting (bash/zsh)

backlog task edit 42 --notes $'Line 1\nLine 2'

Use printf (POSIX portable)

backlog task edit 42 --notes "$(printf 'Line 1\nLine 2')"

PowerShell

backlog task edit 42 --notes "Line 1`nLine 2"

Don't use literal \n - it won't work

❌ backlog task edit 42 --notes "Line 1\nLine 2"

Command Reference

Core Commands

Tasks

backlog task create <title> [options] backlog task list [filters] --plain backlog task <id> --plain backlog task edit <id> [options] backlog task archive <id> backlog task demote <id>

Search

backlog search <query> [filters] --plain

Board & Reports

backlog board backlog browser backlog report --output <file>

Documents

backlog doc create <title> backlog doc list --plain backlog doc edit <id>

Decisions

backlog decision create <title> backlog decision list --plain backlog decision <id> --plain

Common Options

Task creation/editing

-t, --title Task title -d, --description Task description -s, --status Status (To Do, In Progress, Done, Blocked) -a, --assignee Assignee (@username) -l, --labels Comma-separated labels --priority Priority (low, medium, high) --ac Add acceptance criterion --check-ac Check AC by index --uncheck-ac Uncheck AC by index --remove-ac Remove AC by index --plan Implementation plan --notes Implementation notes --append-notes Append to notes --dep Add dependency (task-id) --draft Create as draft -p, --parent Parent task ID

Filters

--plain Plain text output (AI-friendly) --status Filter by status --assignee Filter by assignee --tag Filter by tag --priority Filter by priority --type Filter by type (task, doc, decision)

Tips

• Always use --plain when listing or viewing for AI processing

• Start tasks properly: Set In Progress and assign to yourself

• Check AC as you go: Don't wait until end to mark them complete

• Use multiline properly: Use $'...\n...' syntax for newlines

• Multiple flags work: --check-ac 1 --check-ac 2 --check-ac 3

• Organize with labels: Use consistent labeling scheme

• Atomic tasks: One PR = One task

• PR-ready notes: Format notes as GitHub PR description

• Never edit files directly: Always use CLI commands

• Search is fuzzy: "auth" finds "authentication"

Integration with Git

Workflow

git checkout -b task-42-implement-feature

... implement task 42 ...

backlog task edit 42 --check-ac 1 --check-ac 2 backlog task edit 42 --notes "Implementation complete" backlog task edit 42 -s Done git add . git commit -m "Implement feature X

Refs: task-42" git push

Remember

🎯 Golden Rule: Always use CLI commands. Never edit markdown files directly.

📋 Task Quality: Good AC = Testable outcomes, not implementation steps.

✅ Definition of Done: All AC checked + notes + tests passing + status Done.