johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add workflow examples: multi-phase development and multiple personas (bd-p68x)

Browse Source 
Amp-Thread-ID: https://ampcode.com/threads/T-b0f16435-48af-40ee-be66-ba0636fdd0fb
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-11-05 19:12:58 -08:00
parent 7b60fa0ba9
commit 3ecc16e0e3
3 changed files with 1084 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
examples/README.md
View File

@@ -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-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 - **[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 - **[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 - **[protected-branch/](protected-branch/)** - Protected branch workflow for team collaboration
## Quick Start ## Quick Start

416
examples/multi-phase-development/README.md Normal file
View File

@@ -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

665
examples/multiple-personas/README.md Normal file
View File

@@ -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