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
GitHub	gh CLI	Teams using GitHub Issues
Linear	MCP server	Teams using Linear
Beads	bd CLI	Dependency-aware workflows, AI agents

For simple/solo projects: Use native Tasks (TaskCreate, TaskList, TaskUpdate) instead of backlog-manager.

Configuration

Configure your preferred backend in your project's .agents.yml:

task_management: github  # Options: 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, use native Tasks (TaskCreate, TaskList, TaskUpdate) for simple tracking.

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:

1. Read configuration from project CLAUDE.md
2. Load appropriate reference based on backend setting:
   • github → references/github-backend.md
   • linear → references/linear-backend.md
   • beads → references/beads-backend.md
3. Follow backend-specific instructions for operations

Fallback Behavior

If the configured backend is unavailable:

• GitHub unavailable (gh not authenticated): Fall back to native Tasks
• Linear unavailable (MCP not configured): Fall back to native Tasks
• Beads unavailable (bd not installed or not initialized): Fall back to native Tasks
• 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

Native Tasks (TaskCreate, TaskList, TaskUpdate):

• Session task tracking with file persistence (~/.claude/tasks/)
• Supports dependencies (blockedBy, blocks)
• Can be shared across sessions via CLAUDE_CODE_TASK_LIST_ID env var
• Use for: in-session progress tracking, subagent coordination, simple task lists
• Different from backlog manager: Tasks are ephemeral coordination, backlog is project planning