Beads Issue Tracking with TDD Workflow

Overview

Beads (bd) is a git-native issue tracker that lives in your repository. Use it to track multi-session work with dependency graphs. For TDD workflows, create separate issues for each phase: RED, GREEN, REFACTOR.

When to Use Beads vs TodoWrite

Use Beads	Use TodoWrite
Multi-session work	Single session tasks
Complex dependencies	Linear task lists
Needs persistent context	Ephemeral tracking
TDD phase tracking	Simple checklists
Collaborative work	Solo quick tasks

TDD Workflow with Beads

Phase 1: RED (Failing Tests)

Create an issue for writing the failing test:

bd create --title="RED: [Feature] tests" --type=task --priority=0 --labels="tdd-red,[feature-area]"

Issue content should include:

• What behavior the test should verify
• Expected inputs and outputs
• Edge cases to cover

Mark in_progress when starting:

bd update [issue-id] --status=in_progress

Close when test is written and failing:

bd close [issue-id] --reason="Test written, failing as expected"

Phase 2: GREEN (Minimal Implementation)

Create an issue for the implementation (depends on RED):

bd create --title="GREEN: Implement [Feature]" --type=task --priority=0 --labels="tdd-green,[feature-area]"
bd dep add [green-id] [red-id]  # GREEN depends on RED

Issue content should include:

• Link to the RED issue
• Minimal approach to make tests pass
• No extra features (YAGNI)

Close when tests pass:

bd close [issue-id] --reason="Tests passing"

Phase 3: REFACTOR (Clean Up)

Create an issue for refactoring (depends on GREEN):

bd create --title="REFACTOR: Clean up [Feature]" --type=task --priority=1 --labels="tdd-refactor,[feature-area]"
bd dep add [refactor-id] [green-id]  # REFACTOR depends on GREEN

Issue content should include:

• What needs cleaning (duplication, naming, extraction)
• Keep tests green throughout

Close when refactoring complete:

bd close [issue-id] --reason="Refactored, tests still green"

Essential Commands

Finding Work

bd ready                    # Show issues with no blockers
bd list --status=open       # All open issues
bd list --status=in_progress # Active work
bd blocked                  # See what's blocked and why

Creating Issues

bd create --title="..." --type=task|bug|feature|epic --priority=0-4
# Priority: 0=critical, 1=high, 2=medium, 3=low, 4=backlog

Managing Dependencies

bd dep add [issue] [depends-on]  # issue is blocked by depends-on
bd show [issue]                   # See dependencies and dependents

Updating Status

bd update [id] --status=in_progress  # Claim work
bd update [id] --status=blocked      # Mark blocked
bd close [id]                        # Complete work
bd close [id1] [id2] [id3]          # Close multiple at once

Syncing

bd sync --from-main    # Pull beads updates from main branch
bd sync --status       # Check sync status

TDD Labels Convention

Use these labels consistently:

Label	Phase	Description
tdd-red	RED	Writing failing tests
tdd-green	GREEN	Implementing to pass tests
tdd-refactor	REFACTOR	Cleaning up while green

Plus feature-area labels like: auth, api, ui, database, etc.

Example: Adding User Authentication

# 1. Create RED issue
bd create --title="RED: User authentication tests" \
  --type=task --priority=0 \
  --labels="tdd-red,auth" \
  --description="Write tests for login, logout, session management"

# 2. Create GREEN issue (blocked by RED)
bd create --title="GREEN: Implement user authentication" \
  --type=task --priority=0 \
  --labels="tdd-green,auth"
bd dep add workers-xxxx workers-yyyy  # GREEN blocked by RED

# 3. Create REFACTOR issue (blocked by GREEN)
bd create --title="REFACTOR: Clean up auth module" \
  --type=task --priority=1 \
  --labels="tdd-refactor,auth"
bd dep add workers-zzzz workers-xxxx  # REFACTOR blocked by GREEN

# 4. Work through in order
bd update workers-yyyy --status=in_progress  # Start RED
# ... write tests ...
bd close workers-yyyy --reason="Tests written, failing"

bd update workers-xxxx --status=in_progress  # Start GREEN
# ... implement ...
bd close workers-xxxx --reason="Tests passing"

bd update workers-zzzz --status=in_progress  # Start REFACTOR
# ... refactor ...
bd close workers-zzzz --reason="Refactored, tests green"

Parallel TDD with Subagents

For large features, use parallel subagents to create TDD issue chains:

Launch parallel agents to create beads issues for each module:
- Agent 1: Create RED/GREEN/REFACTOR chain for Module A
- Agent 2: Create RED/GREEN/REFACTOR chain for Module B
- Agent 3: Create RED/GREEN/REFACTOR chain for Module C

Each agent creates 3 issues with proper dependencies.

Session Management

Starting a Session

bd ready                    # Find available work
bd show [id]               # Review issue details
bd update [id] --status=in_progress

Ending a Session

bd close [completed-ids]   # Close finished work
bd sync --from-main        # Pull latest from main
git add . && git commit    # Commit changes

Key Principles

1. One issue per TDD phase - Don't combine RED/GREEN/REFACTOR
2. Dependencies enforce order - GREEN blocked by RED, REFACTOR blocked by GREEN
3. Close immediately - Mark done as soon as phase completes
4. Labels for filtering - Use tdd-* labels to find phase-specific work
5. Sync regularly - Keep beads in sync with main branch