Backlog Md

Backlog.md Task Tracking for Agents

Task tracking system optimized for agent workflows via Backlog.md CLI.

Three Primary Use Cases

1. Implementer: Deferring Issues During Feature Work

File P2-P4 issues discovered during implementation. Use label remediation for deferred review findings.

• Create with plan: You have implementation context at filing time
• Assign priority: See priority guide
• Add type label (required) + app labels (optional)

2. Reviewer: Audit Findings

Create structured issues from security/audit reviews. Link dependencies and assign to milestones.

• Create with plan: You're creating from audit context
• Link dependencies as needed
• Assign priority: Ask user if uncertain (label priority-review)
• Set milestones

3. Worker: Executing Assigned Tasks

Read task fully, understand all fields, follow acceptance criteria and definition of done.

• Claim task: backlog task edit 42 -s "In Progress" -a @myself
• Read everything: All fields, attached files/URLs, linked documentation
• Complete systematically: AC → Implementation Notes → Final Summary → DoD → Done

Absolute Rules

1. CLI only for writes. backlog task edit and backlog task create only. Never edit files directly. 2. Always use `--plain` flag when reading: backlog task 42 --plain, backlog task list --plain 3. Type label required (bug|feature|documentation|refactor|remediation), single value only 4. App labels optional, can be multiple: synapse-pingora, signal-horizon-ui, signal-horizon-api, etc. 5. Custom labels allowed as agent-useful (priority-review, performance, security, etc.)

Implementation Plans: When Required

Never update an existing plan unless explicitly instructed.

Priority System (See references/priority-labels.md for details)

• P0: Critical problems, major breakage
• P1: Legitimate bugs impacting users
• P2: Bugs, edge cases
• P3: Nice-to-have improvements, features we want
• P4: Backlog, future ideas

Unsure about P0-P1? Label with priority-review and let user decide.

Task Completion Checklist

1. Status: "In Progress" + assign self 2. Read: All fields, attached documentation 3. Plan: Add implementation plan (if not deferred from review) 4. Work: Code implementation, mark AC as you complete each 5. Notes: Append progress notes as you go 6. Summary: Add final summary (PR-style) 7. DoD: Check all definition-of-done items 8. Done: Set status "Done"

Essential Commands

# Create issue (required: title, type label, priority)
backlog task create "Title" -d "Description" -l bug -p 2 --ac "AC 1"

# Work a task
backlog task edit 42 -s "In Progress" -a @myself
backlog task 42 --plain              # Read everything
backlog task edit 42 --check-ac 1    # Mark AC complete
backlog task edit 42 --append-notes "Progress here"
backlog task edit 42 --final-summary "PR description"
backlog task edit 42 -s Done

# Search and filter
backlog task list -s "To Do" --plain
backlog search "topic" --plain

See references/cli-reference.md for complete command reference. See references/priority-labels.md for priority and labeling guidelines. See references/issue-creation-guide.md for detailed issue creation patterns.

Backlog.md CLI Command Reference

Complete reference for all backlog CLI commands and flags.

Task Creation

Task Modification

Acceptance Criteria Management

Important AC flag rules:

• Adding: --ac "First" --ac "Second" (multiple flags allowed)
• Checking/unchecking/removing: --check-ac 1 --check-ac 2 (multiple flags allowed)
• Mixed operations work in a single command
• Invalid formats: --check-ac 1,2,3 (no commas), --check-ac 1-3 (no ranges), --check 1 (wrong flag name)

Definition of Done Management

DoD defaults come from definition_of_done in backlog/config.yml. Disable per-task with --no-dod-defaults.

Task Content

Task Operations

Multi-line Input

The CLI preserves input literally. Shells do not convert \n inside normal quotes. To insert real newlines:

Bash/Zsh (ANSI-C quoting)

backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'
backlog task edit 42 --plan $'1. A\n2. B'
backlog task edit 42 --notes $'Done A\nDoing B'
backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'
backlog task edit 42 --final-summary $'Shipped A\nAdded B'
backlog task edit 42 --append-final-summary $'Added X\nAdded Y'

POSIX portable (printf)

backlog task edit 42 --notes "$(printf 'Line1\nLine2')"

PowerShell (backtick n)

backlog task edit 42 --notes "Line1`nLine2"

Note: "...\n..." with regular double quotes passes the literal backslash + n — it does not create a newline.

Implementation Notes Formatting

• Keep notes concise and time-ordered: progress, decisions, blockers
• Use short paragraphs or bullet lists
• Use Markdown bullets (- unordered, 1. ordered)
• Include explicit newlines in --append-notes:

backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy'

Final Summary Formatting

Treat the Final Summary as a PR description. Cover:

• What changed and why
• User impact
• Tests run
• Risks/follow-ups when relevant

Example:

Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes.

Changes:
- Added `finalSummary` to task types and markdown section parsing/serialization.
- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it.

Tests:
- bun test src/test/final-summary.test.ts
- bun test src/test/cli-final-summary.test.ts

Avoid single-line summaries unless the change is truly tiny.

Issue Creation Patterns

Three distinct scenarios with different requirements. Required field: type label + priority.

Scenario 1: Deferred Issues During Feature Implementation

When: You're implementing a feature and discover a bug, edge case, or tech debt. How: File immediately with implementation plan (you have context now). Plan rule: ✅ INCLUDE detailed plan — you'll likely fix it.

Example Workflow

During implementation, you find that error handling is incomplete:

backlog task create "Handle null reference in payment processor" \
  -d "During PaymentService refactor, found case where null processor reference isn't handled, could cause runtime error in production" \
  -l bug,remediation \
  -l synapse-pingora \
  -p 2 \
  --ac "Service returns meaningful error when processor is null" \
  --ac "Edge case handled in existing tests" \
  --plan "1. Add null check before processor call\n2. Add test for null case\n3. Verify with existing integration tests"

Field Checklist

• ✅ Title: Clear, specific (not "Fix bugs")
• ✅ Description: What you found and why it matters
• ✅ Type label: remediation (for deferred review issues)
• ✅ App label(s): What app(s) this affects
• ✅ Priority: Use your judgment (most are P2)
• ✅ Acceptance Criteria: What "done" means
• ✅ Implementation Plan: Steps to fix it

Scenario 2: Reporting Found Issues (No Plan)

When: You discover an issue but won't be implementing it immediately. How: File without plan (let the assignee plan it). Plan rule: ❌ DO NOT include plan — implementer will add it.

Example Workflow

You find a security issue but it's not your responsibility to fix:

backlog task create "Potential XSS vulnerability in user input sanitization" \
  -d "Found unsanitized user input accepted in comment field. Could allow XSS if user provides HTML/script tags." \
  -l bug \
  -l signal-horizon-ui,signal-horizon-api \
  -p 1 \
  --ac "All user inputs sanitized before rendering" \
  --ac "XSS test coverage added"

No plan, no implementation details. Implementer adds plan when they claim it.

Field Checklist

• ✅ Title: Clear, specific
• ✅ Description: What's broken, why it matters
• ✅ Type label: bug|feature|documentation|refactor
• ✅ App label(s): What affects this
• ✅ Priority: P0|P1|P2, use priority-review label if unsure
• ✅ Acceptance Criteria: Success conditions
• ❌ NO Implementation Plan: Leave this for implementer

Scenario 3: Audit Findings (Structured)

When: Reviewer is doing security audit or code quality review. How: Create issues with dependencies and milestones. Plan rule: ✅ INCLUDE plan — you have audit context.

Example Workflow

Security audit finds three related issues:

# Issue 1: Core vulnerability
backlog task create "Remove hardcoded API credentials from environment configs" \
  -d "Security audit found hardcoded credentials in .env.example and config files. Violates OWASP A02:2021. Must use environment variables." \
  -l bug,remediation \
  -l synapse-pingora,signal-horizon-api \
  -p 1 \
  --ac "No hardcoded secrets in any config files" \
  --ac "All secrets loaded from env variables" \
  --plan "1. Scan codebase for hardcoded credentials\n2. Update config to use env vars\n3. Update docs for setup\n4. Run security linter"

# Issue 2: Depends on issue 1
backlog task create "Update deployment docs for credential handling" \
  -d "Related to credential hardcoding fix. Document new env var requirements." \
  -l documentation,remediation \
  -l synapse-pingora,signal-horizon-api \
  -p 2 \
  --ac "Deployment guide includes env var setup" \
  --ac "Example .env.example provided"

# Issue 3: Different finding
backlog task create "Upgrade deprecated crypto library" \
  -d "Audit found crypto-js version 4.1.0 is vulnerable (CVE-2023-xyz). Upgrade to 4.1.5+." \
  -l bug,remediation \
  -l signal-horizon-api \
  -p 1 \
  --ac "Crypto-js updated to 4.1.5 or higher" \
  --ac "All crypto calls still functional after upgrade"

With Dependencies and Milestones

After creating issues, link them:

# Link issue 2 to depend on issue 1
backlog task edit <issue-2-id> --dep <issue-1-id>

# Assign to milestone if needed
backlog task edit <issue-1-id> --milestone "Security Hardening Q1"

Field Checklist

• ✅ Title: Clear, specific
• ✅ Description: What audit found, why it matters, any standards violated
• ✅ Type label: bug|remediation (usually for audit findings)
• ✅ App label(s): What affects this
• ✅ Priority: Based on severity (security = usually P0/P1)
• ✅ Acceptance Criteria: How to verify fix
• ✅ Implementation Plan: Steps to remediate
• ✅ Dependencies (if applicable): Link related issues
• ✅ Milestone (if applicable): Assign to release cycle

Scenario 4: Explicitly Asked to Plan Work

When: User says "Plan out this work" or "Create a task and plan how you'd do it". How: Create with detailed, step-by-step implementation plan. Plan rule: ✅ INCLUDE detailed plan — requirement, not deferral.

Example Workflow

User asks you to plan a feature:

backlog task create "Implement real-time notifications for order status" \
  -d "Add real-time push notifications when order status changes. Users should receive browser notifications and see update in dashboard within 2 seconds." \
  -l feature \
  -l signal-horizon-ui,signal-horizon-api \
  -p 2 \
  --ac "Browser push notification sent on status change" \
  --ac "Dashboard updates in real-time (< 2s latency)" \
  --ac "Works offline gracefully (queues until reconnect)" \
  --ac "E2E test coverage for notification flow" \
  --plan "1. Design notification schema and API contract\n2. Implement backend status change webhook\n3. Add notification queue service\n4. Implement browser notification handler\n5. Add dashboard real-time sync via WebSocket\n6. Write integration tests\n7. Performance test latency requirements"

Detailed Plan Guidelines

• Be thorough: Break down major steps
• Include research: If uncertain about approach, include "1. Research X options"
• Include tests: Add test/validation steps
• Include doc: Add "Update docs" if applicable
• Phase-based: Can organize by layer (backend/frontend) or workflow phase

Decision Tree: Which Scenario?

Are you implementing a feature?
  ├─ Yes, found a bug/tech debt → Scenario 1 (defer with plan)
  └─ No, just reporting it → Scenario 2 (report no plan)

Are you reviewing/auditing?
  └─ Yes → Scenario 3 (audit with plan + dependencies)

Did user explicitly ask for a plan?
  └─ Yes → Scenario 4 (plan as required)

Common Mistakes

Acceptance Criteria Quality

Good (outcome-focused):

• "API returns 200 with correct schema"
• "User sees success message after form submission"
• "Response time < 100ms for 1000 records"

Bad (implementation-focused):

• "Add validateInput() function"
• "Use Promise.all() for parallel requests"
• "Refactor to strategy pattern"

AC should be testable, not prescriptive.

Priority and Labeling System

Agent-optimized priority and labeling system for Backlog.md.

Priority Levels

Required when creating issues. Use the following definitions:

Priority Assignment Strategy

For implementers filing deferred issues during feature work:

• Most deferred issues are P2 (bugs/edge cases found during implementation)
• File P2 by default unless clearly critical (P0/P1)
• If unsure between P2/P3: use P2 (we want to fix it)
• If unsure about P0/P1: Label with priority-review instead of guessing

For reviewers doing audits:

• Security findings: Likely P0/P1
• Code quality issues: P2/P3
• If unsure: Label with priority-review and let user decide later

Don't overthink it. The priority-review label exists for borderline cases.

Labeling System

Type Labels (Required)

Single label per issue. Choose one:

App Labels (Optional)

Can use multiple app labels per issue. Examples:

• synapse-pingora
• signal-horizon-ui
• signal-horizon-api
• Others as needed

Custom Labels (Optional)

Agents can add domain-specific labels for routing:

• performance — performance improvement or investigation
• security — security-related work
• priority-review — priority uncertain, needs user decision
• blocked — waiting on something external
• Others as useful for agent workflows

Labeling Examples

Deferred bug found during code review:

backlog task create "Handle null reference in payment processor" \
  -l bug,remediation \
  -l synapse-pingora \
  -p 2

Security audit finding:

backlog task create "Remove hardcoded credentials from config" \
  -l bug,remediation \
  -l synapse-pingora,signal-horizon-api \
  -p 1 \
  -l priority-review  # If you're unsure about P0 vs P1

Feature work UI component:

backlog task create "Add dark mode toggle to dashboard" \
  -l feature \
  -l signal-horizon-ui \
  -p 3

Documentation for monitoring:

backlog task create "Document monitoring setup for sidecars" \
  -l documentation \
  -p 3

When to Use priority-review Label

If you're filing an issue and the priority is unclear, add the `priority-review` label instead of guessing:

backlog task create "Investigate intermittent timeout in batch processor" \
  -l bug \
  -l synapse-pingora \
  -p 2 \
  -l priority-review  # You think it's P2 but might be P1 if it's affecting production

The user can review these later and adjust priority as needed.

Frequency and Patterns

Based on typical workflows:

• P0/P1 issues: Usually assigned during code review or when critical bugs surface
• P2 issues: Most common during feature implementation (deferred work)
• P3/P4 issues: Less common in review cycles, more from long-term planning
• priority-review: Use liberally when uncertain

Task Execution Workflow

How to work assigned tasks systematically from start to completion.

Step 1: Claim the Task

Set the task to "In Progress" and assign to yourself:

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

Step 2: Read Everything

View the complete task:

backlog task 42 --plain

Read ALL fields:

• Title: What is this task?
• Description: Why does this exist? What's the goal?
• Acceptance Criteria: What defines "done"? (numbered list)
• Definition of Done: Additional checklist items (tests, docs, etc.)
• References: File paths or URLs relevant to implementation
• Documentation: Links to design docs, specs, related materials

Open any attached files/URLs to understand context. You have access to parent directories and can fetch permitted files.

Step 3: Understand the Implementation Plan

If an implementation plan exists, review it. It was created with context about how to approach the work.

If creating a plan (new work, not deferred), create one now:

backlog task edit 42 --plan "1. Research approach\n2. Analyze codebase\n3. Implement\n4. Test"

Share plan with user and wait for approval before writing code.

Step 4: Implement Systematically

Work through acceptance criteria in order. After completing each:

backlog task edit 42 --check-ac 1    # Mark AC #1 complete
# implement more...
backlog task edit 42 --check-ac 2    # Mark AC #2 complete

Record your progress progressively:

backlog task edit 42 --append-notes "Completed AC #1: basic functionality working"
backlog task edit 42 --append-notes "Fixed edge case in AC #2"

Step 5: Write Final Summary

When implementation complete, write PR-quality summary:

backlog task edit 42 --final-summary "Implemented feature X with strategy pattern for extensibility. Added 5 new tests covering edge cases. Files: src/parser.ts, src/strategies/. No breaking changes."

Quality bar: Write as if reviewer will read it. Include what changed, why, scope, and tests.

Step 6: Complete Definition of Done

Check all Definition of Done items:

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

Ensure:

• ✅ Tests pass (run locally)
• ✅ Linting clean
• ✅ Documentation updated if needed
• ✅ No regressions

Step 7: Mark Complete

backlog task edit 42 -s Done

Definition of Done Checklist

Task is truly complete only when ALL are satisfied:

• [ ] All acceptance criteria checked (visible in task)
• [ ] All definition of done items checked (visible in task)
• [ ] Final summary written (PR-quality)
• [ ] Status set to "Done"
• [ ] Tests pass locally
• [ ] Code self-reviewed
• [ ] No regressions introduced
• [ ] Related documentation updated

Understanding Task Fields

Common Patterns

When Task Has No Implementation Plan

Create one before starting code:

backlog task edit 42 --plan "1. Research dependencies\n2. Design approach\n3. Implement\n4. Test and verify"
backlog task edit 42 --append-notes "Plan created and shared with user for approval"

When You Get Blocked

Don't mark task done. Instead: 1. Document the blocker in notes: backlog task edit 42 --append-notes "Blocked on: XYZ service unavailable" 2. Leave task in "In Progress" 3. Notify user of blocker

When Scope Expands

Don't add scope silently. Instead: 1. Update AC first: backlog task edit 42 --ac "New requirement" 2. Or create follow-up task: backlog task create "Follow-up: New feature" 3. Don't exceed original AC without discussion

When AC Is Ambiguous

Read References and Documentation carefully. If still unclear:

• Append notes: backlog task edit 42 --append-notes "AC #2 ambiguous—clarifying with user"
• Pause implementation
• Notify user