Labels in Beads

Labels provide flexible, multi-dimensional categorization for issues beyond the structured fields (status, priority, type). Use labels for cross-cutting concerns, technical metadata, and contextual tagging without schema changes.

Design Philosophy

When to use labels vs. structured fields:

Structured fields (status, priority, type) → Core workflow state
- Status: Where the issue is in the workflow (open, in_progress, blocked, closed)
- Priority: How urgent (0-4)
- Type: What kind of work (bug, feature, task, epic, chore)
Labels → Everything else
- Technical metadata (backend, frontend, api, database)
- Domain/scope (auth, payments, search, analytics)
- Effort estimates (small, medium, large)
- Quality gates (needs-review, needs-tests, breaking-change)
- Team/ownership (team-infra, team-product)
- Release tracking (v1.0, v2.0, backport-candidate)

Quick Start

# Add labels when creating issues
bd create "Fix auth bug" -t bug -p 1 -l auth,backend,urgent

# Add labels to existing issues
bd label add bd-42 security
bd label add bd-42 breaking-change

# List issue labels
bd label list bd-42

# Remove a label
bd label remove bd-42 urgent

# List all labels in use
bd label list-all

# Filter by labels (AND - must have ALL)
bd list --label backend,auth

# Filter by labels (OR - must have AT LEAST ONE)
bd list --label-any frontend,backend

# Combine filters
bd list --status open --priority 1 --label security

Common Label Patterns

1. Technical Component Labels

Identify which part of the system:

backend
frontend
api
database
infrastructure
cli
ui
mobile

Example:

bd create "Add GraphQL endpoint" -t feature -p 2 -l backend,api
bd create "Update login form" -t task -p 2 -l frontend,auth,ui

2. Domain/Feature Area

Group by business domain:

auth
payments
search
analytics
billing
notifications
reporting
admin

Example:

bd list --label payments --status open  # All open payment issues
bd list --label-any auth,security       # Security-related work

3. Size/Effort Estimates

Quick effort indicators:

small     # < 1 day
medium    # 1-3 days
large     # > 3 days

Example:

# Find small quick wins
bd ready --json | jq '.[] | select(.labels[] == "small")'

4. Quality Gates

Track what's needed before closing:

needs-review
needs-tests
needs-docs
breaking-change

Example:

bd label add bd-42 needs-review
bd list --label needs-review --status in_progress

5. Release Management

Track release targeting:

v1.0
v2.0
backport-candidate
release-blocker

Example:

bd list --label v1.0 --status open    # What's left for v1.0?
bd label add bd-42 release-blocker

6. Team/Ownership

Indicate ownership or interest:

team-infra
team-product
team-mobile
needs-triage
help-wanted

Example:

bd list --assignee alice --label team-infra
bd create "Memory leak in cache" -t bug -p 1 -l team-infra,help-wanted

7. Special Markers

Process or workflow flags:

auto-generated     # Created by automation
discovered-from    # Found during other work (also a dep type)
technical-debt
good-first-issue
duplicate
wontfix

Example:

bd create "TODO: Refactor parser" -t chore -p 3 -l technical-debt,auto-generated

Filtering by Labels

AND Filtering (--label)

All specified labels must be present:

# Issues that are BOTH backend AND urgent
bd list --label backend,urgent

# Open bugs that need review AND tests
bd list --status open --type bug --label needs-review,needs-tests

OR Filtering (--label-any)

At least one specified label must be present:

# Issues in frontend OR backend
bd list --label-any frontend,backend

# Security or auth related
bd list --label-any security,auth

Combining AND/OR

Mix both filters for complex queries:

# Backend issues that are EITHER urgent OR a blocker
bd list --label backend --label-any urgent,release-blocker

# Frontend work that needs BOTH review and tests, but in any component
bd list --label needs-review,needs-tests --label-any frontend,ui,mobile

Workflow Examples

Triage Workflow

# Create untriaged issue
bd create "Crash on login" -t bug -p 1 -l needs-triage

# During triage, add context
bd label add bd-42 auth
bd label add bd-42 backend
bd label add bd-42 urgent
bd label remove bd-42 needs-triage

# Find untriaged issues
bd list --label needs-triage

Quality Gate Workflow

# Start work
bd update bd-42 --status in_progress

# Mark quality requirements
bd label add bd-42 needs-tests
bd label add bd-42 needs-docs

# Before closing, verify
bd label list bd-42
# ... write tests and docs ...
bd label remove bd-42 needs-tests
bd label remove bd-42 needs-docs

# Close when gates satisfied
bd close bd-42

Release Planning

# Tag issues for v1.0
bd label add bd-42 v1.0
bd label add bd-43 v1.0
bd label add bd-44 v1.0

# Track v1.0 progress
bd list --label v1.0 --status closed    # Done
bd list --label v1.0 --status open      # Remaining
bd stats  # Overall progress

# Mark critical items
bd label add bd-45 v1.0
bd label add bd-45 release-blocker

Component-Based Work Distribution

# Backend team picks up work
bd ready --json | jq '.[] | select(.labels[]? == "backend")'

# Frontend team finds small tasks
bd list --status open --label frontend,small

# Find help-wanted items for new contributors
bd list --label help-wanted,good-first-issue

Label Management

Listing Labels

# Labels on a specific issue
bd label list bd-42

# All labels in database with usage counts
bd label list-all

# JSON output for scripting
bd label list-all --json

Output:

[
  {"label": "auth", "count": 5},
  {"label": "backend", "count": 12},
  {"label": "frontend", "count": 8}
]

Bulk Operations

Add labels in batch during creation:

bd create "Issue" -l label1,label2,label3

Script to add label to multiple issues:

# Add "needs-review" to all in_progress issues
bd list --status in_progress --json | jq -r '.[].id' | while read id; do
  bd label add "$id" needs-review
done

Remove label from multiple issues:

# Remove "urgent" from closed issues
bd list --status closed --label urgent --json | jq -r '.[].id' | while read id; do
  bd label remove "$id" urgent
done

Integration with Git Workflow

Labels are automatically synced to .beads/issues.jsonl along with all issue data:

# Make changes
bd create "Fix bug" -l backend,urgent
bd label add bd-42 needs-review

# Auto-exported after 5 seconds (or use git hooks for immediate export)
git add .beads/issues.jsonl
git commit -m "Add backend issue"

# After git pull, labels are auto-imported
git pull
bd list --label backend  # Fresh data including labels

Markdown Import/Export

Labels are preserved when importing from markdown:

# Fix Authentication Bug

### Type
bug

### Priority
1

### Labels
auth, backend, urgent, needs-review

### Description
Users can't log in after recent deployment.

bd create -f issue.md
# Creates issue with all four labels

Best Practices

1. Establish Conventions Early

Document your team's label taxonomy:

# Add to project README or CONTRIBUTING.md
- Use lowercase, hyphen-separated (e.g., `good-first-issue`)
- Prefix team labels (e.g., `team-infra`, `team-product`)
- Use consistent size labels (`small`, `medium`, `large`)

2. Don't Overuse Labels

Labels are flexible, but too many can cause confusion. Prefer:

5-10 core technical labels (backend, frontend, api, etc.)
3-5 domain labels per project
Standard process labels (needs-review, needs-tests)
Release labels as needed

3. Clean Up Unused Labels

Periodically review:

bd label list-all
# Remove obsolete labels from issues

4. Use Labels for Filtering, Not Search

Labels are for categorization, not free-text search:

✅ Good: backend, auth, urgent
❌ Bad: fix-the-login-bug, john-asked-for-this

5. Combine with Dependencies

Labels + dependencies = powerful organization:

# Epic with labeled subtasks
bd create "Auth system rewrite" -t epic -p 1 -l auth,v2.0
bd create "Implement JWT" -t task -p 1 -l auth,backend --deps parent-child:bd-42
bd create "Update login UI" -t task -p 1 -l auth,frontend --deps parent-child:bd-42

# Find all v2.0 auth work
bd list --label auth,v2.0

AI Agent Usage

Labels are especially useful for AI agents managing complex workflows:

# Auto-label discovered work
bd create "Found TODO in auth.go" -t task -p 2 -l auto-generated,technical-debt

# Filter for agent review
bd list --label needs-review --status in_progress --json

# Track automation metadata
bd label add bd-42 ai-generated
bd label add bd-42 needs-human-review

Example agent workflow:

# Agent discovers issues during refactor
bd create "Extract validateToken function" -t chore -p 2 \
  -l technical-debt,backend,auth,small \
  --deps discovered-from:bd-10

# Agent marks work for review
bd update bd-42 --status in_progress
# ... agent does work ...
bd label add bd-42 needs-review
bd label add bd-42 ai-generated

# Human reviews and approves
bd label remove bd-42 needs-review
bd label add bd-42 approved
bd close bd-42

Advanced Patterns

Component Matrix

Track issues across multiple dimensions:

# Backend + auth + high priority
bd list --label backend,auth --priority 1

# Any frontend work that's small
bd list --label-any frontend,ui --label small

# Critical issues across all components
bd list --priority 0 --label-any backend,frontend,infrastructure

Sprint Planning

# Label issues for sprint
for id in bd-42 bd-43 bd-44 bd-45; do
  bd label add "$id" sprint-12
done

# Track sprint progress
bd list --label sprint-12 --status closed    # Velocity
bd list --label sprint-12 --status open      # Remaining
bd stats | grep "In Progress"                # Current WIP

Technical Debt Tracking

# Mark debt
bd create "Refactor legacy parser" -t chore -p 3 -l technical-debt,large

# Find debt to tackle
bd list --label technical-debt --label small
bd list --label technical-debt --priority 1  # High-priority debt

Breaking Change Coordination

# Identify breaking changes
bd label add bd-42 breaking-change
bd label add bd-42 v2.0

# Find all breaking changes for next major release
bd list --label breaking-change,v2.0

# Ensure they're documented
bd list --label breaking-change --label needs-docs

Troubleshooting

Labels Not Showing in List

Labels require explicit fetching. The bd list command shows issues but not labels in human output (only in JSON).

# See labels in JSON
bd list --json | jq '.[] | {id, labels}'

# See labels for specific issue
bd show bd-42 --json | jq '.labels'
bd label list bd-42

Label Filtering Not Working

Check label names for exact matches (case-sensitive):

# These are different labels:
bd label add bd-42 Backend    # Capital B
bd list --label backend       # Won't match

# List all labels to see exact names
bd label list-all

Syncing Labels with Git

Labels are included in .beads/issues.jsonl export. If labels seem out of sync:

# Force export
bd export -o .beads/issues.jsonl

# After pull, force import
bd import -i .beads/issues.jsonl

FilesExpand file tree

LABELS.md

Latest commit

History

LABELS.md

File metadata and controls

Labels in Beads

Design Philosophy

Quick Start

Common Label Patterns

1. Technical Component Labels

2. Domain/Feature Area

3. Size/Effort Estimates

4. Quality Gates

5. Release Management

6. Team/Ownership

7. Special Markers

Filtering by Labels

AND Filtering (--label)

OR Filtering (--label-any)

Combining AND/OR

Workflow Examples

Triage Workflow

Quality Gate Workflow

Release Planning

Component-Based Work Distribution

Label Management

Listing Labels

Bulk Operations

Integration with Git Workflow

Markdown Import/Export

Best Practices

1. Establish Conventions Early

2. Don't Overuse Labels

3. Clean Up Unused Labels

4. Use Labels for Filtering, Not Search

5. Combine with Dependencies

AI Agent Usage

Advanced Patterns

Component Matrix

Sprint Planning

Technical Debt Tracking

Breaking Change Coordination

Troubleshooting

Labels Not Showing in List

Label Filtering Not Working

Syncing Labels with Git

See Also