nickcrew/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.