Backlog.md

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

When to Use Docs vs Decisions

Use backlog doc for:

• General project documentation
• Architecture overviews
• Technical specifications
• Design documents
• User guides
• Reference documentation

Use backlog decision for:

• Architectural decisions (ADRs)
• Technology choices
• Design pattern selections
• Infrastructure decisions
• Breaking changes that need justification

Golden Rule for AI Assistants: When you need to create markdown documentation (like architecture docs, decision records, specifications), ALWAYS use backlog doc create or backlog decision create. NEVER create standalone .md files in the project root.

Documents

Documents are stored in backlog/docs/ with the naming pattern doc-XXX - Title.md.

Creating Documents

# Basic document (opens editor for content)
backlog doc create "API Documentation"

# With type
backlog doc create "Architecture Overview" -t architecture

# From file
backlog doc create "README" -p /path/to/readme.md

# Via MCP tools (for AI assistants - preferred method)
# Use mcp__backlog__document_create tool with title and content

Viewing & Listing Documents

# List all documents
backlog doc list --plain

# View specific document
backlog doc view doc-001

# Search documents
backlog search "architecture" --type doc --plain

Document Structure

Documents have YAML frontmatter:

---
id: doc-001
title: API Documentation
type: other
created_date: '2025-11-11 15:22'
---

Document types:

• architecture - System architecture docs
• specification - Technical specifications
• guide - User or developer guides
• reference - Reference documentation
• other - General documentation

Architectural Decisions

Decisions are stored in backlog/decisions/ with the naming pattern decision-XXX - Title.md.

Creating Decisions

# Create decision (opens editor)
backlog decision create "Use PostgreSQL for data storage"

# With status
backlog decision create "Migrate to microservices" --status "proposed"

# Decision statuses:
# - proposed: Decision proposed, under discussion
# - accepted: Decision accepted and implemented
# - rejected: Decision rejected
# - deprecated: Decision no longer valid
# - superseded: Replaced by newer decision

Decision Document Template

When you create a decision, it uses this template:

---
id: decision-XXX
title: Your Decision Title
date: 'YYYY-MM-DD HH:MM'
status: proposed
---
## Context

What is the issue or situation we're addressing?
- What forces are at play?
- What constraints exist?
- What are we trying to achieve?

## Decision

What decision have we made?
- What approach are we taking?
- Why this approach over alternatives?

## Consequences

What are the implications of this decision?
- Positive outcomes
- Negative trade-offs
- What becomes easier/harder?
- Future implications

Viewing & Listing Decisions

# List all decisions
backlog decision list --plain

# View specific decision (if supported)
backlog decision view decision-001

# Search decisions
backlog search "database" --type decision --plain

Writing Good Decisions

Title: Clear, concise statement of decision

# ✅ Good
backlog decision create "Use PostgreSQL for primary database"
backlog decision create "Implement OAuth2 for authentication"
backlog decision create "Adopt microservices architecture"

# ❌ Bad
backlog decision create "Database"
backlog decision create "We should probably use OAuth"

Context: Explain the problem and constraints

## Context

Our current SQLite database cannot handle the increased load from
1000+ concurrent users. We need a production-grade database that:
- Supports high concurrency
- Provides ACID guarantees
- Offers good tooling and community support
- Fits within our budget constraints

We evaluated PostgreSQL, MySQL, and MongoDB.

Decision: State the decision clearly with rationale

## Decision

We will use PostgreSQL as our primary database.

Rationale:
- Excellent ACID compliance and data integrity
- Superior support for complex queries and JSON data
- Strong community and ecosystem
- Our team has PostgreSQL experience
- Free and open source (cost-effective)
- Better performance for our read-heavy workload than MySQL
- More mature than MongoDB for transactional data

Consequences: Document trade-offs honestly

## Consequences

Positive:
- Robust data integrity and ACID compliance
- Better scalability for our use case
- Rich feature set (JSON, full-text search, etc.)
- Excellent monitoring and debugging tools

Negative:
- More complex to set up than SQLite
- Requires separate database server (infrastructure cost)
- Learning curve for team members unfamiliar with PostgreSQL
- Migration effort from existing SQLite database

Trade-offs:
- Operational complexity increases, but data reliability improves
- Higher infrastructure cost, but better performance at scale

Decision Workflow

1. Proposing a Decision

# Create decision as "proposed"
backlog decision create "Adopt GraphQL API" --status "proposed"

# Document the decision
# - Add context about the problem
# - Explain the proposed solution
# - List alternatives considered
# - Document trade-offs

2. Discussion

# Team reviews the decision
# - Add comments/feedback
# - Update decision based on feedback
# - Consider alternatives

3. Accepting or Rejecting

# If accepted
# - Update status to "accepted"
# - Document final rationale
# - Link to implementation tasks

# If rejected
# - Update status to "rejected"
# - Document why it was rejected
# - Preserve for future reference

4. Implementation

# Create tasks to implement decision
backlog task create "Implement PostgreSQL migration" \
  -d "Migrate from SQLite to PostgreSQL (per decision-001)" \
  --ac "Database schema migrated" \
  --ac "All data transferred successfully" \
  --ac "Application updated to use PostgreSQL"

5. Deprecation or Superseding

# If decision becomes outdated
# - Create new decision
# - Mark old decision as "deprecated" or "superseded"
# - Reference new decision in old one

Linking Decisions to Tasks

Always reference decisions in related tasks:

backlog task create "Implement OAuth2 authentication" \
  -d "Implement OAuth2 as decided in decision-002" \
  --ac "OAuth2 flow implemented" \
  --ac "Existing sessions migrated"

# In task notes, reference decision
backlog task edit 42 --notes $'## Decision Reference
This implements decision-002: "Use OAuth2 for authentication"

## Implementation
- Integrated passport-oauth2 library
- Configured Google and GitHub providers
...'

Best Practices for Documentation

Document Organization

# Architecture documents
backlog doc create "System Architecture Overview" -t architecture
backlog doc create "Database Schema Design" -t architecture
backlog doc create "API Architecture" -t architecture

# Specifications
backlog doc create "API Specification v2" -t specification
backlog doc create "Authentication Flow Specification" -t specification

# Guides
backlog doc create "Development Setup Guide" -t guide
backlog doc create "Deployment Guide" -t guide

Version Control

Documents and decisions are version controlled with Git:

• Keep documents up to date
• Use Git history to track changes
• Reference specific versions when needed

Searchability

Use consistent terminology:

# Good - Searchable terms
backlog doc create "Authentication Architecture"
backlog decision create "Use JWT for API authentication"

# Bad - Hard to search
backlog doc create "How we do auth stuff"
backlog decision create "Token thing"

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:

1. ✅ All acceptance criteria checked: --check-ac 1 --check-ac 2 ...
2. ✅ Implementation notes added: --notes "..."
3. ✅ 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

1. Always use --plain when listing or viewing for AI processing
2. For AI: Use backlog for docs: Create architecture/decision docs with backlog doc create or backlog decision create, NEVER create standalone .md files
3. Start tasks properly: Set In Progress and assign to yourself
4. Check AC as you go: Don't wait until end to mark them complete
5. Use multiline properly: Use $'...\n...' syntax for newlines
6. Multiple flags work: --check-ac 1 --check-ac 2 --check-ac 3
7. Organize with labels: Use consistent labeling scheme
8. Atomic tasks: One PR = One task
9. PR-ready notes: Format notes as GitHub PR description
10. Never edit files directly: Always use CLI commands
11. Search is fuzzy: "auth" finds "authentication"
12. Document decisions: Use decision records for architectural choices
13. Link decisions to tasks: Reference decision IDs in related task descriptions

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.

📝 Documentation Rule for AI: Always use backlog doc create or backlog decision create for project documentation. NEVER create standalone .md files in the project root.