Beads Task Tracking Skill

Overview

Beads is an agent-first issue tracker backed by .beads/ (SQLite + JSONL). Use the br CLI to create, update, and complete tasks.

This skill should be used when:

• Creating new tasks from findings or feedback in Beads
• Managing issue lifecycle (open -> in_progress -> closed/deferred)
• Triaging pending items for priority and scope
• Checking or managing dependencies
• Converting PR comments or code findings into tracked Beads issues
• Updating work logs during task execution

If you are unsure whether a repo uses Beads or file-based tasks, use the tasks-router skill first.

Key Concepts

• IDs: Issues have IDs (no filenames).
• Statuses: open, in_progress, deferred, closed.
• Priority: P0-P4 or 0-4 (0 = critical, 4 = backlog).
• Types: task, bug, feature, epic, question, docs.
• Storage: .beads/ contains the database and JSONL export.

Type Mapping

Choose --type based on category:

• Bug -> bug
• Feature -> feature
• Docs / Documentation -> docs
• Question -> question
• Epic -> epic
• Security / Performance / Architecture / Quality / Refactor / Unknown -> task

Field Mapping (Tasks-File -> Beads)

Use Beads fields optimally to preserve structure and enable filtering:

Field purposes:

• description — The problem (what & why)
• design — The solution (how) — technical approach, options, architecture
• notes — Context (findings, resources, decisions)
• acceptance_criteria — Definition of done
• comments — Work log (append-only history)

Use the template at task-template.md for section structure.

Common Workflows

Creating a New Task

To create a new task from findings or feedback:

1. Create the issue with core metadata:

   bashCopy

   br create --title="Short summary" --type=bug --priority=2 \
     --description="Problem statement - what's broken and why it matters" --json
   

2. Add technical design (solutions, architecture, affected files):

   bashCopy

   br update <id> --design="## Proposed Solutions
   
   

Option 1: [Name]

Approach: ... Pros: ... Cons: ... Effort: 2-3 hours Risk: Low

Technical Details

Affected files:

• path/to/file.rb:42 Related components:
• ComponentA, ComponentB" --json
  Copy

3. Add findings and context:
   bashCopy

   br update <id> --notes="## Findings
   

• Root cause: ...
• Investigation showed: ...

Resources

• PR: #1287
• Docs: [link]" --json
  Copy

4. Add acceptance criteria:
   bashCopy

   br update <id> --acceptance-criteria="- [ ] Tests pass
   

• Code reviewed
• Performance acceptable" --json
  Copy

5. Set effort estimate and labels:

   bashCopy

   br update <id> --estimate=120 --add-label "performance" --add-label "db" --json
   

6. Link external references (optional):

   bashCopy

   br update <id> --external-ref="PR#1287" --json
   

When to create a task:

• Requires more than 15-20 minutes of work
• Needs research, planning, or multiple approaches considered
• Has dependencies on other work
• Requires manager approval or prioritization
• Part of larger feature or refactor
• Technical debt needing documentation

When to act immediately instead:

• Issue is trivial (< 15 minutes)
• Complete context available now
• No planning needed
• User explicitly requests immediate action
• Simple bug fix with obvious solution

Triaging Open Items

To triage open tasks:

1. List open items:
   bashCopy

   br list --status=open --sort=priority --json
   

2. For each issue:
   • Read description and notes: br show <id> --json
   • Decide: reprioritize, clarify scope, or defer
3. Update status/priority as needed:
   bashCopy

   br update <id> --priority=1 --json
   br update <id> --status=deferred --defer="2026-03-01" --json
   

Ready work (unblocked):

br ready --json

Managing Dependencies

To add dependencies:

br dep add <issue> <depends-on> --json

To list dependencies:

br dep list <issue> --json

To find dependency cycles:

br dep cycles --json

To see a dependency tree:

br dep tree <issue> --json

Starting Work on a Task

Before working on a task, claim it to set status and assignee atomically:

br update <id> --claim --json

This sets status=in_progress and assignee=<actor> in one step.

Updating Work Logs

When working on a task, add a work log entry as a comment:

cat <<'EONOTE' > /tmp/beads-comment.md
### 2026-02-03 - Session Title

**By:** Claude Code / Developer Name

**Actions:**
- Specific changes made (include file:line references)
- Commands executed
- Tests run
- Results of investigation

**Learnings:**
- What worked / what didn't
- Patterns discovered
- Key insights for future work
EONOTE

br comments add <id> -f /tmp/beads-comment.md --json

Work logs serve as:

• Historical record of investigation
• Documentation of approaches attempted
• Knowledge sharing for team
• Context for future similar work

Completing a Task

To mark a task as complete:

1. Verify acceptance criteria are met
2. Add a final work log entry
3. Close the issue:
   bashCopy

   br close <id> --reason="Completed" --json
   

4. Check for unblocked work:
   bashCopy

   br ready --json
   

Integration with Development Workflows

Quick Reference Commands

Finding work:

# Ready (unblocked) work
br ready --json

# Open high-priority work
br list --status=open --priority-max=1 --json

# Count by status
br count --group-by status --json

Searching:

# Full-text search
br search "payment failure" --json

# By label
br list --label "performance" --json

Data hygiene:

# Show workspace location
br where --json

# Sync DB <-> JSONL
br sync --status --json
br sync --flush-only --json

Key Distinctions

Tasks-file system (this skill):

• Markdown files in tasks/ directory
• Standalone files with YAML frontmatter
• Human-readable, git-friendly
• Use when repo has no .beads/ directory

Tasks-beads system:

• SQLite + JSONL in .beads/ directory
• Managed via br CLI
• Structured fields, richer queries
• Use when repo has .beads/ directory
• See tasks-beads skill for details

Tasks-router skill:

• Routes to tasks-file or tasks-beads based on repo state
• Use when unsure which system applies

TodoWrite tool:

• In-memory task tracking during agent sessions
• Temporary tracking for single conversation
• Not persisted to disk
• Different from both persistent systems above