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>
This commit is contained in:
Steve Yegge
416
examples/multi-phase-development/README.md
Normal file
416
examples/multi-phase-development/README.md
Normal 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
|
||||
Reference in New Issue
Block a user