Beads Integration Skill

Overview

Beads is a git-backed issue tracker for multi-session work with dependencies and persistent memory. All tasks stored in .beads/ directory as markdown files, committed to git, surviving conversation compaction.

Key Capabilities: Task creation/management, status transitions, comments, dependencies, git worktree integration, synchronization.

Reference: See k2-dev-reference.md#beads-cli-commands for complete command syntax.

Core Concepts

Task Structure

• ID: beads-{number}
• Title: Short description
• Description: Detailed requirements and context
• Status: open, in_progress, blocked, closed
• Priority: P0 (critical), P1 (high), P2 (medium), P3 (low)
• Comments: Discussion and updates
• Dependencies: Relationships between tasks

Git-Backed Storage

• Stored in .beads/ as markdown
• Committed to git for persistence
• Survives conversation compaction
• Shareable across team
• Full history via git log

K2-Dev Workflow Integration

Reading Task Context (Before Implementation)

bd show beads-123              # Task details
bd comments beads-123          # All comments for context
bd dep list beads-123          # Check dependencies

Parse output for:

• Title and description (requirements)
• Current status and priority
• Plan and implementation notes in comments
• Blocking dependencies

Creating Tasks from Plans (Planner Agent)

# Epic
bd create "User Authentication System" -d "Epic description" -p P1

# Stories under epic
bd create "JWT Token Implementation" -d "Story" -p P1 --parent=beads-{epic}

# Subtasks
bd create "Auth middleware" -d "Subtask" -p P2 --parent=beads-{story}

# Dependencies (B blocks on A - A must complete before B)
bd dep add beads-{B} --blocks-on=beads-{A}

Adding Implementation Context (Technical Lead)

bd comments beads-123 add "Implementation Plan:
1. Create middleware in src/auth/
2. Use existing JWT library
3. Follow patterns in AGENTS.md
4. Add tests in tests/auth/"

Status Transitions

Proper workflow:

# Technical Lead assigns to Engineer
bd update beads-123 --status in_progress --assignee engineer

# After implementation
bd update beads-123 --status closed

# If blocked
bd update beads-123 --status blocked
bd comments beads-123 add "Blocked by: beads-120 needs merge first"

Creating Follow-Up Tickets (After Review)

When review identifies issues beyond 2 iterations:

# Critical issues
bd create "Fix authentication bypass vulnerability" \
  -d "Critical security issue from PR #456 review. Details: [...]" \
  -p P0

# Link to original
bd comments beads-789 add "Follow-up ticket created: beads-790 (P0)"
bd comments beads-790 add "Follow-up from: beads-789"

Best Practices

Task Descriptions

Good:

Implement JWT authentication middleware

Acceptance Criteria:
- Validates JWT tokens on protected routes
- Returns 401 for invalid/expired tokens
- Follows patterns in src/auth/oauth.ts
- Test coverage >80%

Related: beads-120 (API refactor)

Bad:

Add auth stuff

Comments

Use comments for:

• Implementation plans and notes
• Progress updates
• Blockers and resolutions
• Review feedback summary
• Links to PRs and commits

Dependencies

Set dependencies to:

• Prevent starting work too early
• Show task relationships
• Enable parallel work where possible
• Communicate workflow order

Synchronization

Always sync after:

• Creating or closing tasks
• Session end (automated via hook)
• Before generating reports
• After significant updates

bd sync

Task Hierarchies

Epic (1-2 weeks): bd create "User Management System" -d "Complete user CRUD with roles" -p P1 Story (2-5 days): bd create "User Profile Editing" -d "Users can edit profile" -p P1 --parent=beads-{epic} Subtask (0.5-2 days): bd create "Profile API endpoint" -d "Create PUT /api/users/:id" -p P2 --parent=beads-{story}

Link with dependencies to show hierarchy.

Troubleshooting

Task Not Found:

bd sync                    # Sync first
bd list                    # List all
bd search "keyword"        # Search

Status Not Updating:

• Check for unsaved changes in editor
• Check git conflicts in .beads/
• Run bd sync

Dependency Cycles:

# Check before adding to avoid cycles
bd dep list beads-123
bd dep list beads-456

Git Worktree Integration

bd worktree create beads-123    # Creates ../beads-123/, branch feature/beads-123
bd worktree list                # List worktrees
bd worktree remove beads-123    # Remove worktree

Reference: See git-worktree-workflow skill for detailed patterns.

Agent-Specific Usage

Technical Lead:

• Validates tickets exist and are open
• Reads task context for planning (bd show, bd comments)
• Adds architectural notes as comments
• Closes tasks after merge
• Syncs beads at end

Engineer:

• Reads task description and comments for requirements
• Checks dependencies before starting
• Updates status during implementation
• Creates follow-up tickets when needed

Planner:

• Creates hierarchical task structures
• Sets up dependencies
• Writes detailed descriptions
• Links related tasks

Reviewer:

• Reads task context for review
• Does NOT add comments to beads (uses GitHub PR instead)
• May recommend follow-up tickets

Tester:

• Reads requirements from beads
• Adds test plan as comment
• References beads ticket in test documentation

Reference: See k2-dev-reference.md for complete command syntax, priority levels, and task granularity guidelines.