From 3ecc16e0e3affec0ec171ac53505462bf929027b Mon Sep 17 00:00:00 2001
From: Steve Yegge <stevey@sourcegraph.com>
Date: Wed, 5 Nov 2025 19:12:58 -0800
Subject: [PATCH] Add workflow examples: multi-phase development and multiple
 personas (bd-p68x)

Amp-Thread-ID: https://ampcode.com/threads/T-b0f16435-48af-40ee-be66-ba0636fdd0fb
Co-authored-by: Amp <amp@ampcode.com>
---
 examples/README.md                         |   3 +
 examples/multi-phase-development/README.md | 416 +++++++++++++
 examples/multiple-personas/README.md       | 665 +++++++++++++++++++++
 3 files changed, 1084 insertions(+)
 create mode 100644 examples/multi-phase-development/README.md
 create mode 100644 examples/multiple-personas/README.md

diff --git a/examples/README.md b/examples/README.md
index e462507f..3f09642a 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -13,6 +13,9 @@ This directory contains examples of how to integrate bd with AI agents and workf
 - **[claude-desktop-mcp/](claude-desktop-mcp/)** - MCP server for Claude Desktop integration
 - **[claude-code-skill/](claude-code-skill/)** - Claude Code skill for effective beads usage patterns
 - **[contributor-workflow/](contributor-workflow/)** - OSS contributor setup with separate planning repo
+- **[team-workflow/](team-workflow/)** - Team collaboration with shared repositories
+- **[multi-phase-development/](multi-phase-development/)** - Organize large projects by phases (planning, MVP, iteration, polish)
+- **[multiple-personas/](multiple-personas/)** - Architect/implementer/reviewer role separation
 - **[protected-branch/](protected-branch/)** - Protected branch workflow for team collaboration
 
 ## Quick Start
diff --git a/examples/multi-phase-development/README.md b/examples/multi-phase-development/README.md
new file mode 100644
index 00000000..96272685
--- /dev/null
+++ b/examples/multi-phase-development/README.md
@@ -0,0 +1,416 @@
+# Multi-Phase Development Workflow Example
+
+This example demonstrates how to use beads for large projects with multiple development phases (planning, MVP, iteration, polish).
+
+## Problem
+
+When building complex features, you want to:
+- **Phase 1:** Research and planning
+- **Phase 2:** Build MVP quickly
+- **Phase 3:** Iterate based on feedback
+- **Phase 4:** Polish and production-ready
+- Track discovered work at each phase
+- Keep priorities clear across phases
+
+## Solution
+
+Use beads epics and hierarchical issues to organize work by phase, with priority-based focus.
+
+## Setup
+
+```bash
+# Initialize beads in your project
+cd my-project
+bd init
+
+# Start daemon for auto-sync (optional)
+bd daemon start --auto-commit --auto-push
+```
+
+## Phase 1: Research & Planning
+
+Create the epic and initial planning issues:
+
+```bash
+# Create the main epic
+bd create "Build real-time collaboration system" -t epic -p 1
+# Returns: bd-a1b2c3
+
+# Plan the phases (hierarchical children)
+bd create "Phase 1: Research WebSocket libraries" -p 1
+# Auto-assigned: bd-a1b2c3.1
+
+bd create "Phase 2: Build MVP (basic sync)" -p 1
+# Auto-assigned: bd-a1b2c3.2
+
+bd create "Phase 3: Add conflict resolution" -p 2
+# Auto-assigned: bd-a1b2c3.3
+
+bd create "Phase 4: Production hardening" -p 3
+# Auto-assigned: bd-a1b2c3.4
+
+# Add blocking dependencies (phases must happen in order)
+bd dep add bd-a1b2c3.2 bd-a1b2c3.1 --type blocks
+bd dep add bd-a1b2c3.3 bd-a1b2c3.2 --type blocks
+bd dep add bd-a1b2c3.4 bd-a1b2c3.3 --type blocks
+```
+
+### Research Phase Tasks
+
+```bash
+# Add research tasks for Phase 1
+bd create "Evaluate Socket.IO vs native WebSockets" -p 1 \
+  --deps discovered-from:bd-a1b2c3.1
+
+bd create "Research operational transform vs CRDT" -p 1 \
+  --deps discovered-from:bd-a1b2c3.1
+
+bd create "Document technical decisions" -p 2 \
+  --deps discovered-from:bd-a1b2c3.1
+
+# See what's ready to work on
+bd ready
+# Shows only Phase 1 tasks (nothing blocks them)
+```
+
+## Phase 2: Build MVP
+
+After completing Phase 1 research:
+
+```bash
+# Close Phase 1
+bd close bd-a1b2c3.1 --reason "Research complete, chose Socket.IO + CRDT"
+
+# Phase 2 is now unblocked
+bd ready
+# Shows Phase 2 and its tasks
+
+# Break down MVP work
+bd create "Set up Socket.IO server" -p 1 \
+  --deps discovered-from:bd-a1b2c3.2
+
+bd create "Implement basic CRDT for text" -p 1 \
+  --deps discovered-from:bd-a1b2c3.2
+
+bd create "Build simple UI for testing" -p 2 \
+  --deps discovered-from:bd-a1b2c3.2
+
+# Start implementing
+bd update bd-xyz --status in_progress
+```
+
+### Discovered Work During MVP
+
+You'll discover issues during implementation:
+
+```bash
+# Found a bug while implementing
+bd create "Socket.IO disconnects on network change" -t bug -p 1 \
+  --deps discovered-from:bd-xyz
+
+# Found missing feature
+bd create "Need reconnection logic" -p 1 \
+  --deps discovered-from:bd-xyz
+
+# Technical debt to address later
+bd create "Refactor CRDT code for performance" -p 3 \
+  --deps discovered-from:bd-xyz
+```
+
+## Phase 3: Iteration
+
+After MVP is working:
+
+```bash
+# Close Phase 2
+bd close bd-a1b2c3.2 --reason "MVP working, tested with 2 users"
+
+# Phase 3 is now unblocked
+bd ready
+
+# Add iteration tasks
+bd create "Handle concurrent edits properly" -p 1 \
+  --deps discovered-from:bd-a1b2c3.3
+
+bd create "Add conflict indicators in UI" -p 2 \
+  --deps discovered-from:bd-a1b2c3.3
+
+bd create "Test with 10+ concurrent users" -p 1 \
+  --deps discovered-from:bd-a1b2c3.3
+```
+
+### Feedback-Driven Discovery
+
+```bash
+# User testing reveals issues
+bd create "Cursor positions get out of sync" -t bug -p 0 \
+  --deps discovered-from:bd-a1b2c3.3
+
+bd create "Large documents cause lag" -t bug -p 1 \
+  --deps discovered-from:bd-a1b2c3.3
+
+# Feature requests
+bd create "Add presence awareness (who's online)" -p 2 \
+  --deps discovered-from:bd-a1b2c3.3
+```
+
+## Phase 4: Production Hardening
+
+Final polish before production:
+
+```bash
+# Close Phase 3
+bd close bd-a1b2c3.3 --reason "Conflict resolution working well"
+
+# Phase 4 is now unblocked
+bd ready
+
+# Add hardening tasks
+bd create "Add error monitoring (Sentry)" -p 1 \
+  --deps discovered-from:bd-a1b2c3.4
+
+bd create "Load test with 100 users" -p 1 \
+  --deps discovered-from:bd-a1b2c3.4
+
+bd create "Security audit: XSS, injection" -p 0 \
+  --deps discovered-from:bd-a1b2c3.4
+
+bd create "Write deployment runbook" -p 2 \
+  --deps discovered-from:bd-a1b2c3.4
+
+bd create "Add metrics and dashboards" -p 2 \
+  --deps discovered-from:bd-a1b2c3.4
+```
+
+## Viewing Progress
+
+### See All Phases
+
+```bash
+# View the entire dependency tree
+bd dep tree bd-a1b2c3
+
+# Example output:
+# bd-a1b2c3 (epic) - Build real-time collaboration system
+# ├─ bd-a1b2c3.1 [CLOSED] - Phase 1: Research
+# │  ├─ bd-abc [CLOSED] - Evaluate Socket.IO
+# │  ├─ bd-def [CLOSED] - Research CRDT
+# │  └─ bd-ghi [CLOSED] - Document decisions
+# ├─ bd-a1b2c3.2 [CLOSED] - Phase 2: MVP
+# │  ├─ bd-jkl [CLOSED] - Socket.IO server
+# │  ├─ bd-mno [CLOSED] - Basic CRDT
+# │  └─ bd-pqr [IN_PROGRESS] - Testing UI
+# ├─ bd-a1b2c3.3 [OPEN] - Phase 3: Iteration
+# │  └─ (blocked by bd-a1b2c3.2)
+# └─ bd-a1b2c3.4 [OPEN] - Phase 4: Hardening
+#    └─ (blocked by bd-a1b2c3.3)
+```
+
+### Current Phase Status
+
+```bash
+# See only open issues
+bd list --status open
+
+# See current phase's ready work
+bd ready
+
+# See high-priority issues across all phases
+bd list --priority 0 --status open
+bd list --priority 1 --status open
+```
+
+### Progress Metrics
+
+```bash
+# Overall stats
+bd stats
+
+# Issues by phase
+bd list | grep "Phase 1"
+bd list | grep "Phase 2"
+```
+
+## Priority Management Across Phases
+
+### Dynamic Priority Adjustment
+
+As you learn more, priorities change:
+
+```bash
+# Started as P2, but user feedback made it critical
+bd update bd-xyz --priority 0
+
+# Started as P1, but can wait until later phase
+bd update bd-abc --priority 3
+```
+
+### Focus on Current Phase
+
+```bash
+# See only P0-P1 issues (urgent work)
+bd ready | grep -E "P0|P1"
+
+# See backlog for future phases (P3-P4)
+bd list --priority 3 --status open
+bd list --priority 4 --status open
+```
+
+## Example: Full Workflow
+
+```bash
+# Day 1: Planning
+bd create "Build auth system" -t epic -p 1  # bd-a1b2
+bd create "Phase 1: Research OAuth providers" -p 1  # bd-a1b2.1
+bd create "Phase 2: Implement OAuth flow" -p 1  # bd-a1b2.2
+bd create "Phase 3: Add session management" -p 2  # bd-a1b2.3
+bd create "Phase 4: Security audit" -p 1  # bd-a1b2.4
+bd dep add bd-a1b2.2 bd-a1b2.1 --type blocks
+bd dep add bd-a1b2.3 bd-a1b2.2 --type blocks
+bd dep add bd-a1b2.4 bd-a1b2.3 --type blocks
+
+# Week 1: Phase 1 (Research)
+bd ready  # Shows Phase 1 tasks
+bd create "Compare Auth0 vs Firebase" -p 1 --deps discovered-from:bd-a1b2.1
+bd update bd-xyz --status in_progress
+# ... research complete ...
+bd close bd-a1b2.1 --reason "Chose Auth0"
+
+# Week 2-3: Phase 2 (Implementation)
+bd ready  # Now shows Phase 2 tasks
+bd create "Set up Auth0 tenant" -p 1 --deps discovered-from:bd-a1b2.2
+bd create "Implement login callback" -p 1 --deps discovered-from:bd-a1b2.2
+bd create "Handle token refresh" -p 1 --deps discovered-from:bd-a1b2.2
+# ... discovered bugs ...
+bd create "Callback fails on Safari" -t bug -p 0 --deps discovered-from:bd-abc
+bd close bd-a1b2.2 --reason "OAuth flow working"
+
+# Week 4: Phase 3 (Sessions)
+bd ready  # Shows Phase 3 tasks
+bd create "Implement Redis session store" -p 1 --deps discovered-from:bd-a1b2.3
+bd create "Add session timeout handling" -p 2 --deps discovered-from:bd-a1b2.3
+bd close bd-a1b2.3 --reason "Sessions working"
+
+# Week 5: Phase 4 (Security)
+bd ready  # Shows Phase 4 tasks
+bd create "Review OWASP top 10" -p 1 --deps discovered-from:bd-a1b2.4
+bd create "Add CSRF protection" -p 0 --deps discovered-from:bd-a1b2.4
+bd create "Pen test with security team" -p 1 --deps discovered-from:bd-a1b2.4
+bd close bd-a1b2.4 --reason "Security audit passed"
+
+# Epic complete!
+bd close bd-a1b2 --reason "Auth system in production"
+```
+
+## Best Practices
+
+### 1. Keep Phases Focused
+
+Each phase should have clear exit criteria:
+
+```bash
+# Good: Specific, measurable
+bd create "Phase 1: Research (exit: chosen solution + ADR doc)" -p 1
+
+# Bad: Vague
+bd create "Phase 1: Look at stuff" -p 1
+```
+
+### 2. Use Priorities Within Phases
+
+Not everything in a phase is equally urgent:
+
+```bash
+# Critical path
+bd create "Implement core sync algorithm" -p 0 --deps discovered-from:bd-a1b2.2
+
+# Nice to have, can wait
+bd create "Add dark mode to test UI" -p 3 --deps discovered-from:bd-a1b2.2
+```
+
+### 3. Link Discovered Work
+
+Always link to parent issue/phase:
+
+```bash
+# Maintains context
+bd create "Bug found during testing" -t bug -p 1 \
+  --deps discovered-from:bd-a1b2.3
+
+# Can trace back to which phase/feature it came from
+bd dep tree bd-a1b2
+```
+
+### 4. Don't Block on Low-Priority Work
+
+If a phase has P3-P4 issues, don't let them block the next phase:
+
+```bash
+# Move nice-to-haves to backlog, unblock Phase 2
+bd update bd-xyz --priority 4
+bd close bd-a1b2.1 --reason "Core research done, polish can wait"
+```
+
+### 5. Regular Review
+
+Check progress weekly:
+
+```bash
+# What's done?
+bd list --status closed --limit 20
+
+# What's stuck?
+bd list --status blocked
+
+# What's ready?
+bd ready
+```
+
+## Common Patterns
+
+### MVP → Iteration Loop
+
+```bash
+# MVP phase
+bd create "Phase 2: MVP (basic features)" -p 1
+bd create "Phase 3: Iteration (feedback loop)" -p 2
+bd dep add bd-phase3 bd-phase2 --type blocks
+
+# After MVP, discover improvements
+bd create "Add feature X (user requested)" -p 1 \
+  --deps discovered-from:bd-phase3
+bd create "Fix UX issue Y" -p 2 \
+  --deps discovered-from:bd-phase3
+```
+
+### Parallel Workstreams
+
+Not all phases must be sequential:
+
+```bash
+# Frontend and backend can happen in parallel
+bd create "Frontend: Build UI mockups" -p 1
+bd create "Backend: API design" -p 1
+
+# No blocking dependency between them
+# Both show up in 'bd ready'
+```
+
+### Rollback Planning
+
+Plan for failure:
+
+```bash
+# Phase 3: Launch
+bd create "Phase 3: Deploy to production" -p 1
+
+# Contingency plan (related, not blocking)
+bd create "Rollback plan if deploy fails" -p 1
+bd dep add bd-rollback bd-phase3 --type related
+```
+
+## See Also
+
+- [Team Workflow](../team-workflow/) - Collaborate across phases
+- [Contributor Workflow](../contributor-workflow/) - External contributions
+- [Multiple Personas Example](../multiple-personas/) - Architect/implementer split
diff --git a/examples/multiple-personas/README.md b/examples/multiple-personas/README.md
new file mode 100644
index 00000000..6b12c8fe
--- /dev/null
+++ b/examples/multiple-personas/README.md
@@ -0,0 +1,665 @@
+# Multiple Personas Workflow Example
+
+This example demonstrates how to use beads when different roles work on the same project (architect, implementer, reviewer, etc.).
+
+## Problem
+
+Complex projects involve different personas with different concerns:
+- **Architect:** System design, technical decisions, high-level planning
+- **Implementer:** Write code, fix bugs, implement features
+- **Reviewer:** Code review, quality gates, testing
+- **Product:** Requirements, priorities, user stories
+
+Each persona needs:
+- Different views of the same work
+- Clear handoffs between roles
+- Track discovered work in context
+
+## Solution
+
+Use beads labels, priorities, and dependencies to organize work by persona, with clear ownership and handoffs.
+
+## Setup
+
+```bash
+# Initialize beads
+cd my-project
+bd init
+
+# Start daemon for auto-sync (optional for teams)
+bd daemon start --auto-commit --auto-push
+```
+
+## Persona: Architect
+
+The architect creates high-level design and makes technical decisions.
+
+### Create Architecture Epic
+
+```bash
+# Main epic
+bd create "Design new caching layer" -t epic -p 1
+# Returns: bd-a1b2c3
+
+# Add architecture label
+bd label add bd-a1b2c3 architecture
+
+# Architecture tasks
+bd create "Research caching strategies (Redis vs Memcached)" -p 1 \
+  --deps discovered-from:bd-a1b2c3
+bd label add bd-xyz architecture
+
+bd create "Write ADR: Caching layer design" -p 1 \
+  --deps discovered-from:bd-a1b2c3
+bd label add bd-abc architecture
+
+bd create "Design cache invalidation strategy" -p 1 \
+  --deps discovered-from:bd-a1b2c3
+bd label add bd-def architecture
+```
+
+### View Architect Work
+
+```bash
+# See only architecture issues
+bd list --label architecture
+
+# See architecture issues that are ready
+bd list --label architecture --status open | grep -v blocked
+
+# High-priority architecture decisions
+bd list --label architecture --priority 0
+bd list --label architecture --priority 1
+```
+
+### Handoff to Implementer
+
+When design is complete, create implementation tasks:
+
+```bash
+# Close architecture tasks
+bd close bd-xyz --reason "Decided on Redis with write-through"
+bd close bd-abc --reason "ADR-007 published"
+
+# Create implementation tasks with labels
+bd create "Implement Redis connection pool" -p 1 \
+  --deps discovered-from:bd-a1b2c3
+bd label add bd-impl1 implementation
+
+bd create "Add cache middleware to API routes" -p 1 \
+  --deps discovered-from:bd-a1b2c3
+bd label add bd-impl2 implementation
+
+# Link implementation to architecture
+bd dep add bd-impl1 bd-abc --type related  # Based on ADR
+bd dep add bd-impl2 bd-abc --type related
+```
+
+## Persona: Implementer
+
+The implementer writes code based on architecture decisions.
+
+### View Implementation Work
+
+```bash
+# See only implementation tasks
+bd list --label implementation --status open
+
+# See what's ready to implement
+bd ready | grep implementation
+
+# High-priority bugs to fix
+bd list --label implementation --type bug --priority 0
+bd list --label implementation --type bug --priority 1
+```
+
+### Claim and Implement
+
+```bash
+# Claim a task
+bd update bd-impl1 --status in_progress
+
+# During implementation, discover issues
+bd create "Need connection retry logic" -t bug -p 1 \
+  --deps discovered-from:bd-impl1
+bd label add bd-bug1 implementation bug
+
+bd create "Add metrics for cache hit rate" -p 2 \
+  --deps discovered-from:bd-impl1
+bd label add bd-metric1 implementation observability
+
+# Complete implementation
+bd close bd-impl1 --reason "Redis pool working, tested locally"
+```
+
+### Handoff to Reviewer
+
+```bash
+# Mark ready for review
+bd create "Code review: Redis caching layer" -p 1
+bd label add bd-review1 review
+
+# Link to implementation
+bd dep add bd-review1 bd-impl1 --type related
+bd dep add bd-review1 bd-impl2 --type related
+```
+
+## Persona: Reviewer
+
+The reviewer checks code quality, tests, and approvals.
+
+### View Review Work
+
+```bash
+# See all review tasks
+bd list --label review --status open
+
+# See what's ready for review
+bd ready | grep review
+
+# High-priority reviews
+bd list --label review --priority 0
+bd list --label review --priority 1
+```
+
+### Perform Review
+
+```bash
+# Claim review
+bd update bd-review1 --status in_progress
+
+# Found issues during review
+bd create "Add unit tests for retry logic" -t task -p 1 \
+  --deps discovered-from:bd-review1
+bd label add bd-test1 implementation testing
+
+bd create "Fix: connection leak on timeout" -t bug -p 0 \
+  --deps discovered-from:bd-review1
+bd label add bd-bug2 implementation bug critical
+
+bd create "Document Redis config options" -p 2 \
+  --deps discovered-from:bd-review1
+bd label add bd-doc1 documentation
+
+# Block review until issues fixed
+bd dep add bd-review1 bd-test1 --type blocks
+bd dep add bd-review1 bd-bug2 --type blocks
+```
+
+### Approve or Request Changes
+
+```bash
+# After fixes, approve
+bd close bd-review1 --reason "LGTM, all tests pass"
+
+# Or request changes
+bd update bd-review1 --status blocked
+# (blockers will show up in dependency tree)
+```
+
+## Persona: Product Owner
+
+The product owner manages priorities and requirements.
+
+### View Product Work
+
+```bash
+# See all features
+bd list --type feature
+
+# See high-priority work
+bd list --priority 0
+bd list --priority 1
+
+# See what's in progress
+bd list --status in_progress
+
+# See what's blocked
+bd list --status blocked
+```
+
+### Prioritize Work
+
+```bash
+# Bump priority based on customer feedback
+bd update bd-impl2 --priority 0
+
+# Lower priority for nice-to-haves
+bd update bd-metric1 --priority 3
+
+# Add product label to track customer-facing work
+bd label add bd-impl2 customer-facing
+```
+
+### Create User Stories
+
+```bash
+# User story
+bd create "As a user, I want faster page loads" -t feature -p 1
+bd label add bd-story1 user-story customer-facing
+
+# Link technical work to user story
+bd dep add bd-impl1 bd-story1 --type related
+bd dep add bd-impl2 bd-story1 --type related
+```
+
+## Multi-Persona Workflow Example
+
+### Week 1: Architecture Phase
+
+**Architect:**
+
+```bash
+# Create epic
+bd create "Implement rate limiting" -t epic -p 1  # bd-epic1
+bd label add bd-epic1 architecture
+
+# Research
+bd create "Research rate limiting algorithms" -p 1 \
+  --deps discovered-from:bd-epic1
+bd label add bd-research1 architecture research
+
+bd update bd-research1 --status in_progress
+# ... research done ...
+bd close bd-research1 --reason "Chose token bucket algorithm"
+
+# Design
+bd create "Write ADR: Rate limiting design" -p 1 \
+  --deps discovered-from:bd-epic1
+bd label add bd-adr1 architecture documentation
+
+bd close bd-adr1 --reason "ADR-012 approved"
+```
+
+### Week 2: Implementation Phase
+
+**Implementer:**
+
+```bash
+# See what's ready to implement
+bd ready | grep implementation
+
+# Create implementation tasks based on architecture
+bd create "Implement token bucket algorithm" -p 1 \
+  --deps discovered-from:bd-epic1
+bd label add bd-impl1 implementation
+bd dep add bd-impl1 bd-adr1 --type related
+
+bd create "Add rate limit middleware" -p 1 \
+  --deps discovered-from:bd-epic1
+bd label add bd-impl2 implementation
+
+# Claim and start
+bd update bd-impl1 --status in_progress
+
+# Discover issues
+bd create "Need distributed rate limiting (Redis)" -t bug -p 1 \
+  --deps discovered-from:bd-impl1
+bd label add bd-bug1 implementation bug
+```
+
+**Architect (consulted):**
+
+```bash
+# Architect reviews discovered issue
+bd show bd-bug1
+bd update bd-bug1 --priority 0  # Escalate to critical
+bd label add bd-bug1 architecture  # Architect will handle
+
+# Make decision
+bd create "Design: Distributed rate limiting" -p 0 \
+  --deps discovered-from:bd-bug1
+bd label add bd-design1 architecture
+
+bd close bd-design1 --reason "Use Redis with sliding window"
+```
+
+**Implementer (continues):**
+
+```bash
+# Implement based on architecture decision
+bd create "Add Redis sliding window for rate limits" -p 0 \
+  --deps discovered-from:bd-design1
+bd label add bd-impl3 implementation
+
+bd close bd-impl1 --reason "Token bucket working"
+bd close bd-impl3 --reason "Redis rate limiting working"
+```
+
+### Week 3: Review Phase
+
+**Reviewer:**
+
+```bash
+# See what's ready for review
+bd list --label review
+
+# Create review task
+bd create "Code review: Rate limiting" -p 1
+bd label add bd-review1 review
+bd dep add bd-review1 bd-impl1 --type related
+bd dep add bd-review1 bd-impl3 --type related
+
+bd update bd-review1 --status in_progress
+
+# Found issues
+bd create "Add integration tests for Redis" -t task -p 1 \
+  --deps discovered-from:bd-review1
+bd label add bd-test1 testing implementation
+
+bd create "Missing error handling for Redis down" -t bug -p 0 \
+  --deps discovered-from:bd-review1
+bd label add bd-bug2 implementation bug critical
+
+# Block review
+bd dep add bd-review1 bd-test1 --type blocks
+bd dep add bd-review1 bd-bug2 --type blocks
+```
+
+**Implementer (fixes):**
+
+```bash
+# Fix review findings
+bd update bd-bug2 --status in_progress
+bd close bd-bug2 --reason "Added circuit breaker for Redis"
+
+bd update bd-test1 --status in_progress
+bd close bd-test1 --reason "Integration tests passing"
+```
+
+**Reviewer (approves):**
+
+```bash
+# Review unblocked
+bd close bd-review1 --reason "Approved, merging PR"
+```
+
+**Product Owner (closes epic):**
+
+```bash
+# Feature shipped!
+bd close bd-epic1 --reason "Rate limiting in production"
+```
+
+## Label Organization
+
+### Recommended Labels
+
+```bash
+# Role labels
+architecture, implementation, review, product
+
+# Type labels
+bug, feature, task, chore, documentation
+
+# Status labels
+critical, blocked, waiting-feedback, needs-design
+
+# Domain labels
+frontend, backend, infrastructure, database
+
+# Quality labels
+testing, security, performance, accessibility
+
+# Customer labels
+customer-facing, user-story, feedback
+```
+
+### View by Label Combination
+
+```bash
+# Critical bugs for implementers
+bd list --label implementation --label bug --label critical
+
+# Architecture issues needing review
+bd list --label architecture --label review
+
+# Customer-facing features
+bd list --label customer-facing --type feature
+
+# Backend implementation work
+bd list --label backend --label implementation --status open
+```
+
+## Filtering by Persona
+
+### Architect View
+
+```bash
+# My work
+bd list --label architecture --status open
+
+# Design decisions to make
+bd list --label architecture --label needs-design
+
+# High-priority architecture
+bd list --label architecture --priority 0
+bd list --label architecture --priority 1
+```
+
+### Implementer View
+
+```bash
+# My work
+bd list --label implementation --status open
+
+# Ready to implement
+bd ready | grep implementation
+
+# Bugs to fix
+bd list --label implementation --type bug --priority 0
+bd list --label implementation --type bug --priority 1
+
+# Blocked work
+bd list --label implementation --status blocked
+```
+
+### Reviewer View
+
+```bash
+# Reviews waiting
+bd list --label review --status open
+
+# Critical reviews
+bd list --label review --priority 0
+
+# Blocked reviews
+bd list --label review --status blocked
+```
+
+### Product Owner View
+
+```bash
+# All customer-facing work
+bd list --label customer-facing
+
+# Features in progress
+bd list --type feature --status in_progress
+
+# Blocked work (needs attention)
+bd list --status blocked
+
+# High-priority items across all personas
+bd list --priority 0
+```
+
+## Handoff Patterns
+
+### Architecture → Implementation
+
+```bash
+# Architect creates spec
+bd create "Design: New payment API" -p 1
+bd label add bd-design1 architecture documentation
+
+# When done, create implementation tasks
+bd create "Implement Stripe integration" -p 1
+bd label add bd-impl1 implementation
+bd dep add bd-impl1 bd-design1 --type related
+
+bd close bd-design1 --reason "Spec complete, ready for implementation"
+```
+
+### Implementation → Review
+
+```bash
+# Implementer finishes
+bd close bd-impl1 --reason "Stripe working, PR ready"
+
+# Create review task
+bd create "Code review: Stripe integration" -p 1
+bd label add bd-review1 review
+bd dep add bd-review1 bd-impl1 --type related
+```
+
+### Review → Product
+
+```bash
+# Reviewer approves
+bd close bd-review1 --reason "Approved, deployed to staging"
+
+# Product tests in staging
+bd create "UAT: Test Stripe in staging" -p 1
+bd label add bd-uat1 product testing
+bd dep add bd-uat1 bd-review1 --type related
+
+# Product approves for production
+bd close bd-uat1 --reason "UAT passed, deploying to prod"
+```
+
+## Best Practices
+
+### 1. Use Labels Consistently
+
+```bash
+# Good: Clear role separation
+bd label add bd-123 architecture
+bd label add bd-456 implementation
+bd label add bd-789 review
+
+# Bad: Mixing concerns
+# (same issue shouldn't be both architecture and implementation)
+```
+
+### 2. Link Related Work
+
+```bash
+# Always link implementation to architecture
+bd dep add bd-impl bd-arch --type related
+
+# Link bugs to features
+bd dep add bd-bug bd-feature --type discovered-from
+```
+
+### 3. Clear Handoffs
+
+```bash
+# Document why closing
+bd close bd-arch --reason "Design complete, created bd-impl1 and bd-impl2 for implementation"
+
+# Not: "done" (too vague)
+```
+
+### 4. Escalate When Needed
+
+```bash
+# Implementer discovers architectural issue
+bd create "Current design doesn't handle edge case X" -t bug -p 0
+bd label add bd-issue architecture  # Tag for architect
+bd label add bd-issue needs-design  # Flag as needing design
+```
+
+### 5. Regular Syncs
+
+```bash
+# Daily: Each persona checks their work
+bd list --label architecture --status open  # Architect
+bd list --label implementation --status open  # Implementer
+bd list --label review --status open  # Reviewer
+
+# Weekly: Team reviews together
+bd stats  # Overall progress
+bd list --status blocked  # What's stuck?
+bd ready  # What's ready to work on?
+```
+
+## Common Patterns
+
+### Spike Then Implement
+
+```bash
+# Architect creates research spike
+bd create "Spike: Evaluate GraphQL vs REST" -p 1
+bd label add bd-spike1 architecture research
+
+bd close bd-spike1 --reason "Chose GraphQL, created implementation tasks"
+
+# Implementation follows
+bd create "Implement GraphQL API" -p 1
+bd label add bd-impl1 implementation
+bd dep add bd-impl1 bd-spike1 --type related
+```
+
+### Bug Triage
+
+```bash
+# Bug reported
+bd create "App crashes on large files" -t bug -p 1
+
+# Implementer investigates
+bd update bd-bug1 --label implementation
+bd update bd-bug1 --status in_progress
+
+# Discovers architectural issue
+bd create "Need streaming uploads, not buffering" -t bug -p 0
+bd label add bd-arch1 architecture
+bd dep add bd-arch1 bd-bug1 --type discovered-from
+
+# Architect designs solution
+bd update bd-arch1 --label architecture
+bd close bd-arch1 --reason "Designed streaming upload flow"
+
+# Implementer fixes
+bd update bd-bug1 --status in_progress
+bd close bd-bug1 --reason "Implemented streaming uploads"
+```
+
+### Feature Development
+
+```bash
+# Product creates user story
+bd create "Users want bulk import" -t feature -p 1
+bd label add bd-story1 user-story product
+
+# Architect designs
+bd create "Design: Bulk import system" -p 1
+bd label add bd-design1 architecture
+bd dep add bd-design1 bd-story1 --type related
+
+# Implementation tasks
+bd create "Implement CSV parser" -p 1
+bd label add bd-impl1 implementation
+bd dep add bd-impl1 bd-design1 --type related
+
+bd create "Implement batch processor" -p 1
+bd label add bd-impl2 implementation
+bd dep add bd-impl2 bd-design1 --type related
+
+# Review
+bd create "Code review: Bulk import" -p 1
+bd label add bd-review1 review
+bd dep add bd-review1 bd-impl1 --type blocks
+bd dep add bd-review1 bd-impl2 --type blocks
+
+# Product UAT
+bd create "UAT: Bulk import" -p 1
+bd label add bd-uat1 product testing
+bd dep add bd-uat1 bd-review1 --type blocks
+```
+
+## See Also
+
+- [Multi-Phase Development](../multi-phase-development/) - Organize work by phase
+- [Team Workflow](../team-workflow/) - Collaborate across personas
+- [Contributor Workflow](../contributor-workflow/) - External contributions
+- [Labels Documentation](../../LABELS.md) - Label management guide