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
# 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:
# 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
# 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:
# 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:
# 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:
# 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
# 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:
# 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
# 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
# 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
# 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:
# 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
# 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
# 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:
# 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:
# 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:
# 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:
# 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:
# 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
# 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:
# 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:
# 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 - Collaborate across phases
- Contributor Workflow - External contributions
- Multiple Personas Example - Architect/implementer split