backlog-manager
Manage backlog items across multiple backends (files, GitHub Issues, Linear, Beads). Configure task_management in .agents.yml.
When & Why to Use This Skill
The Backlog Manager is a powerful Claude skill designed to unify task tracking across multiple platforms including GitHub Issues, Linear, Beads, and local files. It enables developers to seamlessly bridge the gap between AI-assisted coding and professional project management by providing a standardized interface for creating, prioritizing, and updating work items. By automating the transition from code-level insights to actionable tickets, it ensures project continuity and enhances team productivity.
Use Cases
- Workflow Integration: Automatically convert code review findings and complex PR comments into tracked backlog items in GitHub or Linear.
- Technical Debt Management: Document and prioritize refactoring needs or architectural improvements discovered during development sessions to ensure they are addressed in future sprints.
- Cross-Backend Synchronization: Switch between local markdown files for solo prototyping and enterprise tools like Linear for team collaboration without changing the command interface.
- Dependency-Aware Planning: Utilize the Beads backend to manage complex workflows that require strict dependency tracking and AI agent coordination.
- Session Persistence: Ensure that tasks requiring more than 20 minutes of work or multi-step research are persisted across different AI chat sessions for long-term tracking.
| name | backlog-manager |
|---|---|
| description | Manage backlog items across multiple backends (files, GitHub Issues, Linear, Beads). Configure task_management in .agents.yml. |
Backlog Manager Skill
Overview
The backlog manager provides a unified interface for tracking work items across different task management systems. Choose your backend based on team preferences and existing tooling.
Supported Backends:
| Backend | Integration | Best For |
|---|---|---|
| Files | Local markdown in docs/todos/ |
Solo developers, simple projects |
| GitHub | gh CLI |
Teams using GitHub Issues |
| Linear | MCP server | Teams using Linear |
| Beads | bd CLI |
Dependency-aware workflows, AI agents |
Configuration
Configure your preferred backend in your project's .agents.yml:
task_management: github # Options: file, github, linear, beads
# Workflow labels (for github/linear backends)
workflow_labels:
- backlog
- in-progress
- ready-for-review
- done
# Beads configuration (when task_management: beads)
# beads_prefix: myapp # Optional: custom issue prefix
Default: If no configuration is found, uses file-based backend.
When to Use This Skill
Create a backlog item when:
- Work requires more than 15-20 minutes
- Needs research, planning, or multiple approaches considered
- Has dependencies on other work
- Requires approval or prioritization
- Part of larger feature or refactor
- Technical debt needing documentation
Act immediately instead when:
- Issue is trivial (< 15 minutes)
- Complete context available now
- No planning needed
- User explicitly requests immediate action
- Simple bug fix with obvious solution
Core Concepts
Status Lifecycle
All backends follow this status workflow:
pending → ready → complete
| Status | Meaning |
|---|---|
| pending | Needs triage/approval before work begins |
| ready | Approved and ready for implementation |
| complete | Work finished, acceptance criteria met |
Priority Levels
| Priority | Meaning |
|---|---|
| p1 | Critical - blocks other work or users |
| p2 | Important - should be done soon |
| p3 | Nice-to-have - can wait |
Core Operations
Each backend implements these operations:
| Operation | Purpose |
|---|---|
| CREATE | Add new backlog item |
| LIST | Query existing items |
| UPDATE | Modify item (status, priority, details) |
| COMPLETE | Mark item as done |
Backend Selection
When this skill is invoked:
- Read configuration from project CLAUDE.md
- Load appropriate reference based on
backendsetting:files→references/file-backend.mdgithub→references/github-backend.mdlinear→references/linear-backend.mdbeads→references/beads-backend.md
- Follow backend-specific instructions for operations
Fallback Behavior
If the configured backend is unavailable:
- GitHub unavailable (gh not authenticated): Fall back to files
- Linear unavailable (MCP not configured): Fall back to files
- Beads unavailable (bd not installed or not initialized): Fall back to files
- Warn user about the fallback
Integration with Development Workflows
| Trigger | Flow |
|---|---|
| Code review findings | Review → Create items → Triage → Work |
| PR comments | Resolve PR → Create items for complex fixes |
| Planning sessions | Brainstorm → Create items → Prioritize → Work |
| Technical debt | Document → Create item → Schedule |
| Feature requests | Analyze → Create item → Prioritize |
Key Distinctions
Backlog manager (this skill):
- Persisted tracking across sessions
- Multiple backend options
- Team collaboration
- Project/sprint planning
TodoWrite tool:
- In-memory task tracking during single session
- Temporary progress tracking
- Not persisted to disk
- Different purpose from backlog management