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

Scenario	Include Plan?	Reason
Deferred review issues	✅ YES	You have audit/review context now
Reporting found issues	❌ NO	Implementer will plan when they work it
Explicitly asked to plan work	✅ YES (detailed)	Required per instruction
Regular task work	After claiming, before coding	Don't add at creation, add after starting

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.