Merge remote-tracking branch 'origin/main'
Amp-Thread-ID: https://ampcode.com/threads/T-810952b1-e2a2-4913-97cb-90b12287ff40 Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
File diff suppressed because one or more lines are too long
239
.beads/issues.jsonl
Normal file
239
.beads/issues.jsonl
Normal file
File diff suppressed because one or more lines are too long
10
AGENTS.md
10
AGENTS.md
@@ -1048,6 +1048,16 @@ Happy coding! 🔗
|
||||
bd init --prefix bd
|
||||
```
|
||||
|
||||
**OSS Contributor?** Use the contributor wizard for fork workflows:
|
||||
```bash
|
||||
bd init --contributor # Interactive setup for separate planning repo
|
||||
```
|
||||
|
||||
**Team Member?** Use the team wizard for branch workflows:
|
||||
```bash
|
||||
bd init --team # Interactive setup for team collaboration
|
||||
```
|
||||
|
||||
**Check for ready work:**
|
||||
```bash
|
||||
bd ready --json
|
||||
|
||||
@@ -10,6 +10,30 @@ go build -o bd ./cmd/bd
|
||||
./bd --help
|
||||
```
|
||||
|
||||
## Initialize
|
||||
|
||||
First time in a repository:
|
||||
|
||||
```bash
|
||||
# Basic setup
|
||||
bd init
|
||||
|
||||
# OSS contributor (fork workflow with separate planning repo)
|
||||
bd init --contributor
|
||||
|
||||
# Team member (branch workflow for collaboration)
|
||||
bd init --team
|
||||
|
||||
# Protected main branch (GitHub/GitLab)
|
||||
bd init --branch beads-metadata
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
- Create `.beads/` directory and database
|
||||
- Import existing issues from git (if any)
|
||||
- Prompt to install git hooks (recommended)
|
||||
- Auto-start daemon for sync
|
||||
|
||||
## Your First Issues
|
||||
|
||||
```bash
|
||||
|
||||
@@ -102,6 +102,12 @@ Beads is designed for **AI coding agents** to use on your behalf. Setup takes 30
|
||||
# In your project root:
|
||||
bd init
|
||||
|
||||
# For OSS contributors (fork workflow):
|
||||
bd init --contributor
|
||||
|
||||
# For team members (branch workflow):
|
||||
bd init --team
|
||||
|
||||
# For protected branches (GitHub/GitLab):
|
||||
bd init --branch beads-metadata
|
||||
|
||||
|
||||
@@ -27,6 +27,8 @@ With --no-db: creates .beads/ directory and issues.jsonl file instead of SQLite
|
||||
prefix, _ := cmd.Flags().GetString("prefix")
|
||||
quiet, _ := cmd.Flags().GetBool("quiet")
|
||||
branch, _ := cmd.Flags().GetString("branch")
|
||||
contributor, _ := cmd.Flags().GetBool("contributor")
|
||||
team, _ := cmd.Flags().GetBool("team")
|
||||
|
||||
// Initialize config (PersistentPreRun doesn't run for init command)
|
||||
if err := config.Initialize(); err != nil {
|
||||
@@ -272,6 +274,24 @@ bd.db
|
||||
}
|
||||
}
|
||||
|
||||
// Run contributor wizard if --contributor flag is set
|
||||
if contributor {
|
||||
if err := runContributorWizard(ctx, store); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Error running contributor wizard: %v\n", err)
|
||||
_ = store.Close()
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
// Run team wizard if --team flag is set
|
||||
if team {
|
||||
if err := runTeamWizard(ctx, store); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Error running team wizard: %v\n", err)
|
||||
_ = store.Close()
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
if err := store.Close(); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to close database: %v\n", err)
|
||||
}
|
||||
@@ -331,6 +351,8 @@ func init() {
|
||||
initCmd.Flags().StringP("prefix", "p", "", "Issue prefix (default: current directory name)")
|
||||
initCmd.Flags().BoolP("quiet", "q", false, "Suppress output (quiet mode)")
|
||||
initCmd.Flags().StringP("branch", "b", "", "Git branch for beads commits (default: current branch)")
|
||||
initCmd.Flags().Bool("contributor", false, "Run OSS contributor setup wizard")
|
||||
initCmd.Flags().Bool("team", false, "Run team workflow setup wizard")
|
||||
rootCmd.AddCommand(initCmd)
|
||||
}
|
||||
|
||||
|
||||
237
cmd/bd/init_contributor.go
Normal file
237
cmd/bd/init_contributor.go
Normal file
@@ -0,0 +1,237 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"github.com/fatih/color"
|
||||
"github.com/steveyegge/beads/internal/storage"
|
||||
)
|
||||
|
||||
// runContributorWizard guides the user through OSS contributor setup
|
||||
func runContributorWizard(ctx context.Context, store storage.Storage) error {
|
||||
green := color.New(color.FgGreen).SprintFunc()
|
||||
cyan := color.New(color.FgCyan).SprintFunc()
|
||||
yellow := color.New(color.FgYellow).SprintFunc()
|
||||
bold := color.New(color.Bold).SprintFunc()
|
||||
|
||||
fmt.Printf("\n%s %s\n\n", bold("bd"), bold("Contributor Workflow Setup Wizard"))
|
||||
fmt.Println("This wizard will configure beads for OSS contribution.")
|
||||
fmt.Println()
|
||||
|
||||
// Step 1: Detect fork relationship
|
||||
fmt.Printf("%s Detecting git repository setup...\n", cyan("▶"))
|
||||
|
||||
isFork, upstreamURL, err := detectForkSetup()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to detect git setup: %w", err)
|
||||
}
|
||||
|
||||
if isFork {
|
||||
fmt.Printf("%s Detected fork workflow (upstream: %s)\n", green("✓"), upstreamURL)
|
||||
} else {
|
||||
fmt.Printf("%s No upstream remote detected\n", yellow("⚠"))
|
||||
fmt.Println("\n For fork workflows, add an 'upstream' remote:")
|
||||
fmt.Println(" git remote add upstream <original-repo-url>")
|
||||
fmt.Println()
|
||||
|
||||
// Ask if they want to continue anyway
|
||||
fmt.Print("Continue with contributor setup? [y/N]: ")
|
||||
reader := bufio.NewReader(os.Stdin)
|
||||
response, _ := reader.ReadString('\n')
|
||||
response = strings.TrimSpace(strings.ToLower(response))
|
||||
|
||||
if response != "y" && response != "yes" {
|
||||
fmt.Println("Setup cancelled.")
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
// Step 2: Check push access to origin
|
||||
fmt.Printf("\n%s Checking repository access...\n", cyan("▶"))
|
||||
|
||||
hasPushAccess, originURL := checkPushAccess()
|
||||
|
||||
if hasPushAccess {
|
||||
fmt.Printf("%s You have push access to origin (%s)\n", green("✓"), originURL)
|
||||
fmt.Printf(" %s You can commit directly to this repository.\n", yellow("⚠"))
|
||||
fmt.Println()
|
||||
fmt.Print("Do you want to use a separate planning repo anyway? [Y/n]: ")
|
||||
reader := bufio.NewReader(os.Stdin)
|
||||
response, _ := reader.ReadString('\n')
|
||||
response = strings.TrimSpace(strings.ToLower(response))
|
||||
|
||||
if response == "n" || response == "no" {
|
||||
fmt.Println("\nSetup cancelled. Your issues will be stored in the current repository.")
|
||||
return nil
|
||||
}
|
||||
} else {
|
||||
fmt.Printf("%s Read-only access to origin (%s)\n", green("✓"), originURL)
|
||||
fmt.Println(" Planning repo recommended to keep experimental work separate.")
|
||||
}
|
||||
|
||||
// Step 3: Configure planning repository
|
||||
fmt.Printf("\n%s Setting up planning repository...\n", cyan("▶"))
|
||||
|
||||
homeDir, err := os.UserHomeDir()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to get home directory: %w", err)
|
||||
}
|
||||
|
||||
defaultPlanningRepo := filepath.Join(homeDir, ".beads-planning")
|
||||
|
||||
fmt.Printf("\nWhere should contributor planning issues be stored?\n")
|
||||
fmt.Printf("Default: %s\n", cyan(defaultPlanningRepo))
|
||||
fmt.Print("Planning repo path [press Enter for default]: ")
|
||||
|
||||
reader := bufio.NewReader(os.Stdin)
|
||||
planningPath, _ := reader.ReadString('\n')
|
||||
planningPath = strings.TrimSpace(planningPath)
|
||||
|
||||
if planningPath == "" {
|
||||
planningPath = defaultPlanningRepo
|
||||
}
|
||||
|
||||
// Expand ~ if present
|
||||
if strings.HasPrefix(planningPath, "~/") {
|
||||
planningPath = filepath.Join(homeDir, planningPath[2:])
|
||||
}
|
||||
|
||||
// Create planning repository if it doesn't exist
|
||||
if _, err := os.Stat(planningPath); os.IsNotExist(err) {
|
||||
fmt.Printf("\nCreating planning repository at %s\n", cyan(planningPath))
|
||||
|
||||
if err := os.MkdirAll(planningPath, 0750); err != nil {
|
||||
return fmt.Errorf("failed to create planning repo directory: %w", err)
|
||||
}
|
||||
|
||||
// Initialize git repo in planning directory
|
||||
cmd := exec.Command("git", "init")
|
||||
cmd.Dir = planningPath
|
||||
if err := cmd.Run(); err != nil {
|
||||
return fmt.Errorf("failed to initialize git in planning repo: %w", err)
|
||||
}
|
||||
|
||||
// Initialize beads in planning repo
|
||||
beadsDir := filepath.Join(planningPath, ".beads")
|
||||
if err := os.MkdirAll(beadsDir, 0750); err != nil {
|
||||
return fmt.Errorf("failed to create .beads in planning repo: %w", err)
|
||||
}
|
||||
|
||||
// Create issues.jsonl
|
||||
jsonlPath := filepath.Join(beadsDir, "beads.jsonl")
|
||||
if err := os.WriteFile(jsonlPath, []byte{}, 0644); err != nil {
|
||||
return fmt.Errorf("failed to create issues.jsonl: %w", err)
|
||||
}
|
||||
|
||||
// Create README in planning repo
|
||||
readmePath := filepath.Join(planningPath, "README.md")
|
||||
readmeContent := fmt.Sprintf(`# Beads Planning Repository
|
||||
|
||||
This repository stores contributor planning issues for OSS projects.
|
||||
|
||||
## Purpose
|
||||
|
||||
- Keep experimental planning separate from upstream PRs
|
||||
- Track discovered work and implementation notes
|
||||
- Maintain private todos and design exploration
|
||||
|
||||
## Usage
|
||||
|
||||
Issues here are automatically created when working on forked repositories.
|
||||
|
||||
Created by: bd init --contributor
|
||||
`)
|
||||
if err := os.WriteFile(readmePath, []byte(readmeContent), 0644); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create README: %v\n", err)
|
||||
}
|
||||
|
||||
// Initial commit in planning repo
|
||||
cmd = exec.Command("git", "add", ".")
|
||||
cmd.Dir = planningPath
|
||||
_ = cmd.Run()
|
||||
|
||||
cmd = exec.Command("git", "commit", "-m", "Initial commit: beads planning repository")
|
||||
cmd.Dir = planningPath
|
||||
_ = cmd.Run()
|
||||
|
||||
fmt.Printf("%s Planning repository created\n", green("✓"))
|
||||
} else {
|
||||
fmt.Printf("%s Using existing planning repository\n", green("✓"))
|
||||
}
|
||||
|
||||
// Step 4: Configure contributor routing
|
||||
fmt.Printf("\n%s Configuring contributor auto-routing...\n", cyan("▶"))
|
||||
|
||||
// Set contributor.planning_repo config
|
||||
if err := store.SetConfig(ctx, "contributor.planning_repo", planningPath); err != nil {
|
||||
return fmt.Errorf("failed to set planning repo config: %w", err)
|
||||
}
|
||||
|
||||
// Set contributor.auto_route to true
|
||||
if err := store.SetConfig(ctx, "contributor.auto_route", "true"); err != nil {
|
||||
return fmt.Errorf("failed to enable auto-routing: %w", err)
|
||||
}
|
||||
|
||||
fmt.Printf("%s Auto-routing enabled\n", green("✓"))
|
||||
|
||||
// Step 5: Summary
|
||||
fmt.Printf("\n%s %s\n\n", green("✓"), bold("Contributor setup complete!"))
|
||||
|
||||
fmt.Println("Configuration:")
|
||||
fmt.Printf(" Current repo issues: %s\n", cyan(".beads/beads.jsonl"))
|
||||
fmt.Printf(" Planning repo issues: %s\n", cyan(filepath.Join(planningPath, ".beads/beads.jsonl")))
|
||||
fmt.Println()
|
||||
fmt.Println("How it works:")
|
||||
fmt.Println(" • Issues you create will route to the planning repo")
|
||||
fmt.Println(" • Planning stays out of your PRs to upstream")
|
||||
fmt.Println(" • Use 'bd list' to see issues from both repos")
|
||||
fmt.Println()
|
||||
fmt.Printf("Try it: %s\n", cyan("bd create \"Plan feature X\" -p 2"))
|
||||
fmt.Println()
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// detectForkSetup checks if we're in a fork by looking for upstream remote
|
||||
func detectForkSetup() (isFork bool, upstreamURL string, err error) {
|
||||
cmd := exec.Command("git", "remote", "get-url", "upstream")
|
||||
output, err := cmd.Output()
|
||||
if err != nil {
|
||||
// No upstream remote found
|
||||
return false, "", nil
|
||||
}
|
||||
|
||||
upstreamURL = strings.TrimSpace(string(output))
|
||||
return true, upstreamURL, nil
|
||||
}
|
||||
|
||||
// checkPushAccess determines if we have push access to origin
|
||||
func checkPushAccess() (hasPush bool, originURL string) {
|
||||
// Get origin URL
|
||||
cmd := exec.Command("git", "remote", "get-url", "origin")
|
||||
output, err := cmd.Output()
|
||||
if err != nil {
|
||||
return false, ""
|
||||
}
|
||||
|
||||
originURL = strings.TrimSpace(string(output))
|
||||
|
||||
// SSH URLs indicate likely push access (git@github.com:...)
|
||||
if strings.HasPrefix(originURL, "git@") {
|
||||
return true, originURL
|
||||
}
|
||||
|
||||
// HTTPS URLs typically indicate read-only clone
|
||||
if strings.HasPrefix(originURL, "https://") {
|
||||
return false, originURL
|
||||
}
|
||||
|
||||
// Other protocols (file://, etc.) assume push access
|
||||
return true, originURL
|
||||
}
|
||||
224
cmd/bd/init_team.go
Normal file
224
cmd/bd/init_team.go
Normal file
@@ -0,0 +1,224 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
|
||||
"github.com/fatih/color"
|
||||
"github.com/steveyegge/beads/internal/storage"
|
||||
)
|
||||
|
||||
// runTeamWizard guides the user through team workflow setup
|
||||
func runTeamWizard(ctx context.Context, store storage.Storage) error {
|
||||
green := color.New(color.FgGreen).SprintFunc()
|
||||
cyan := color.New(color.FgCyan).SprintFunc()
|
||||
yellow := color.New(color.FgYellow).SprintFunc()
|
||||
bold := color.New(color.Bold).SprintFunc()
|
||||
|
||||
fmt.Printf("\n%s %s\n\n", bold("bd"), bold("Team Workflow Setup Wizard"))
|
||||
fmt.Println("This wizard will configure beads for team collaboration.")
|
||||
fmt.Println()
|
||||
|
||||
// Step 1: Check if we're in a git repository
|
||||
fmt.Printf("%s Detecting git repository setup...\n", cyan("▶"))
|
||||
|
||||
if !isGitRepo() {
|
||||
fmt.Printf("%s Not in a git repository\n", yellow("⚠"))
|
||||
fmt.Println("\n Initialize git first:")
|
||||
fmt.Println(" git init")
|
||||
fmt.Println()
|
||||
return fmt.Errorf("not in a git repository")
|
||||
}
|
||||
|
||||
// Get current branch
|
||||
currentBranch, err := getGitBranch()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to get current branch: %w", err)
|
||||
}
|
||||
|
||||
fmt.Printf("%s Current branch: %s\n", green("✓"), currentBranch)
|
||||
|
||||
// Step 2: Check for protected main branch
|
||||
fmt.Printf("\n%s Checking branch configuration...\n", cyan("▶"))
|
||||
|
||||
fmt.Println("\nIs your main branch protected (prevents direct commits)?")
|
||||
fmt.Println(" GitHub: Settings → Branches → Branch protection rules")
|
||||
fmt.Println(" GitLab: Settings → Repository → Protected branches")
|
||||
fmt.Print("\nProtected main branch? [y/N]: ")
|
||||
|
||||
reader := bufio.NewReader(os.Stdin)
|
||||
response, _ := reader.ReadString('\n')
|
||||
response = strings.TrimSpace(strings.ToLower(response))
|
||||
|
||||
protectedMain := (response == "y" || response == "yes")
|
||||
|
||||
var syncBranch string
|
||||
|
||||
if protectedMain {
|
||||
fmt.Printf("\n%s Protected main detected\n", green("✓"))
|
||||
fmt.Println("\n Beads will commit issue updates to a separate branch.")
|
||||
fmt.Printf(" Default sync branch: %s\n", cyan("beads-metadata"))
|
||||
fmt.Print("\n Sync branch name [press Enter for default]: ")
|
||||
|
||||
branchName, _ := reader.ReadString('\n')
|
||||
branchName = strings.TrimSpace(branchName)
|
||||
|
||||
if branchName == "" {
|
||||
syncBranch = "beads-metadata"
|
||||
} else {
|
||||
syncBranch = branchName
|
||||
}
|
||||
|
||||
fmt.Printf("\n%s Sync branch set to: %s\n", green("✓"), syncBranch)
|
||||
|
||||
// Set sync.branch config
|
||||
if err := store.SetConfig(ctx, "sync.branch", syncBranch); err != nil {
|
||||
return fmt.Errorf("failed to set sync branch: %w", err)
|
||||
}
|
||||
|
||||
// Create the sync branch if it doesn't exist
|
||||
fmt.Printf("\n%s Creating sync branch...\n", cyan("▶"))
|
||||
|
||||
if err := createSyncBranch(syncBranch); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create sync branch: %v\n", err)
|
||||
fmt.Println(" You can create it manually: git checkout -b", syncBranch)
|
||||
} else {
|
||||
fmt.Printf("%s Sync branch created\n", green("✓"))
|
||||
}
|
||||
|
||||
} else {
|
||||
fmt.Printf("%s Direct commits to %s\n", green("✓"), currentBranch)
|
||||
syncBranch = currentBranch
|
||||
}
|
||||
|
||||
// Step 3: Configure team settings
|
||||
fmt.Printf("\n%s Configuring team settings...\n", cyan("▶"))
|
||||
|
||||
// Set team.enabled to true
|
||||
if err := store.SetConfig(ctx, "team.enabled", "true"); err != nil {
|
||||
return fmt.Errorf("failed to enable team mode: %w", err)
|
||||
}
|
||||
|
||||
// Set team.sync_branch
|
||||
if err := store.SetConfig(ctx, "team.sync_branch", syncBranch); err != nil {
|
||||
return fmt.Errorf("failed to set team sync branch: %w", err)
|
||||
}
|
||||
|
||||
fmt.Printf("%s Team mode enabled\n", green("✓"))
|
||||
|
||||
// Step 4: Configure auto-sync
|
||||
fmt.Println("\n Enable automatic sync (daemon commits/pushes)?")
|
||||
fmt.Println(" • Auto-commit: Commits issue changes every 5 seconds")
|
||||
fmt.Println(" • Auto-push: Pushes commits to remote")
|
||||
fmt.Print("\nEnable auto-sync? [Y/n]: ")
|
||||
|
||||
response, _ = reader.ReadString('\n')
|
||||
response = strings.TrimSpace(strings.ToLower(response))
|
||||
|
||||
autoSync := !(response == "n" || response == "no")
|
||||
|
||||
if autoSync {
|
||||
if err := store.SetConfig(ctx, "daemon.auto_commit", "true"); err != nil {
|
||||
return fmt.Errorf("failed to enable auto-commit: %w", err)
|
||||
}
|
||||
|
||||
if err := store.SetConfig(ctx, "daemon.auto_push", "true"); err != nil {
|
||||
return fmt.Errorf("failed to enable auto-push: %w", err)
|
||||
}
|
||||
|
||||
fmt.Printf("%s Auto-sync enabled\n", green("✓"))
|
||||
} else {
|
||||
fmt.Printf("%s Auto-sync disabled (manual sync with 'bd sync')\n", yellow("⚠"))
|
||||
}
|
||||
|
||||
// Step 5: Summary
|
||||
fmt.Printf("\n%s %s\n\n", green("✓"), bold("Team setup complete!"))
|
||||
|
||||
fmt.Println("Configuration:")
|
||||
if protectedMain {
|
||||
fmt.Printf(" Protected main: %s\n", cyan("yes"))
|
||||
fmt.Printf(" Sync branch: %s\n", cyan(syncBranch))
|
||||
fmt.Printf(" Commits will go to: %s\n", cyan(syncBranch))
|
||||
fmt.Printf(" Merge to main via: %s\n", cyan("Pull Request"))
|
||||
} else {
|
||||
fmt.Printf(" Protected main: %s\n", cyan("no"))
|
||||
fmt.Printf(" Commits will go to: %s\n", cyan(currentBranch))
|
||||
}
|
||||
|
||||
if autoSync {
|
||||
fmt.Printf(" Auto-sync: %s\n", cyan("enabled"))
|
||||
} else {
|
||||
fmt.Printf(" Auto-sync: %s\n", cyan("disabled"))
|
||||
}
|
||||
|
||||
fmt.Println()
|
||||
fmt.Println("How it works:")
|
||||
fmt.Println(" • All team members work on the same repository")
|
||||
fmt.Println(" • Issues are shared via git commits")
|
||||
fmt.Println(" • Use 'bd list' to see all team's issues")
|
||||
|
||||
if protectedMain {
|
||||
fmt.Println(" • Issue updates commit to", syncBranch)
|
||||
fmt.Println(" • Periodically merge", syncBranch, "to main via PR")
|
||||
}
|
||||
|
||||
if autoSync {
|
||||
fmt.Println(" • Daemon automatically commits and pushes changes")
|
||||
} else {
|
||||
fmt.Println(" • Run 'bd sync' manually to sync changes")
|
||||
}
|
||||
|
||||
fmt.Println()
|
||||
fmt.Printf("Try it: %s\n", cyan("bd create \"Team planning issue\" -p 2"))
|
||||
fmt.Println()
|
||||
|
||||
if protectedMain {
|
||||
fmt.Println("Next steps:")
|
||||
fmt.Printf(" 1. %s\n", "Share the "+syncBranch+" branch with your team")
|
||||
fmt.Printf(" 2. %s\n", "Team members: git pull origin "+syncBranch)
|
||||
fmt.Printf(" 3. %s\n", "Periodically: merge "+syncBranch+" to main via PR")
|
||||
fmt.Println()
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// getGitBranch returns the current git branch name
|
||||
func getGitBranch() (string, error) {
|
||||
cmd := exec.Command("git", "rev-parse", "--abbrev-ref", "HEAD")
|
||||
output, err := cmd.Output()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
|
||||
return strings.TrimSpace(string(output)), nil
|
||||
}
|
||||
|
||||
// createSyncBranch creates a new branch for beads sync
|
||||
func createSyncBranch(branchName string) error {
|
||||
// Check if branch already exists
|
||||
cmd := exec.Command("git", "rev-parse", "--verify", branchName)
|
||||
if err := cmd.Run(); err == nil {
|
||||
// Branch exists, nothing to do
|
||||
return nil
|
||||
}
|
||||
|
||||
// Create new branch from current HEAD
|
||||
cmd = exec.Command("git", "checkout", "-b", branchName)
|
||||
if err := cmd.Run(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Switch back to original branch
|
||||
currentBranch, err := getGitBranch()
|
||||
if err == nil && currentBranch != branchName {
|
||||
cmd = exec.Command("git", "checkout", "-")
|
||||
_ = cmd.Run() // Ignore error, branch creation succeeded
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
@@ -483,5 +483,5 @@ bd create "Issue" -p 1
|
||||
|
||||
- [bd-8rd](/.beads/beads.jsonl#bd-8rd) - Migration and onboarding epic
|
||||
- [bd-mlcz](/.beads/beads.jsonl#bd-mlcz) - `bd migrate` command (planned)
|
||||
- [bd-kla1](/.beads/beads.jsonl#bd-kla1) - `bd init --contributor` wizard (planned)
|
||||
- [bd-twlr](/.beads/beads.jsonl#bd-twlr) - `bd init --team` wizard (planned)
|
||||
- [bd-kla1](/.beads/beads.jsonl#bd-kla1) - `bd init --contributor` wizard ✅ implemented
|
||||
- [bd-twlr](/.beads/beads.jsonl#bd-twlr) - `bd init --team` wizard ✅ implemented
|
||||
|
||||
@@ -12,6 +12,11 @@ This directory contains examples of how to integrate bd with AI agents and workf
|
||||
<!-- REMOVED (bd-4c74): branch-merge example - collision resolution no longer needed with hash IDs -->
|
||||
- **[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
|
||||
|
||||
|
||||
211
examples/contributor-workflow/README.md
Normal file
211
examples/contributor-workflow/README.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# OSS Contributor Workflow Example
|
||||
|
||||
This example demonstrates how to use beads' contributor workflow to keep your planning issues separate from upstream PRs when contributing to open-source projects.
|
||||
|
||||
## Problem
|
||||
|
||||
When contributing to OSS projects, you want to:
|
||||
- Track your planning, todos, and design notes
|
||||
- Keep experimental work organized
|
||||
- **NOT** pollute upstream PRs with your personal planning issues
|
||||
|
||||
## Solution
|
||||
|
||||
Use `bd init --contributor` to set up a separate planning repository that never gets committed to the upstream project.
|
||||
|
||||
## Setup
|
||||
|
||||
### Step 1: Fork and Clone
|
||||
|
||||
```bash
|
||||
# Fork the project on GitHub, then clone your fork
|
||||
git clone https://github.com/YOUR_USERNAME/project.git
|
||||
cd project
|
||||
|
||||
# Add upstream remote (important for fork detection!)
|
||||
git remote add upstream https://github.com/ORIGINAL_OWNER/project.git
|
||||
```
|
||||
|
||||
### Step 2: Initialize Beads with Contributor Wizard
|
||||
|
||||
```bash
|
||||
# Run the contributor setup wizard
|
||||
bd init --contributor
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
1. ✅ Detect that you're in a fork (checks for 'upstream' remote)
|
||||
2. ✅ Prompt you to create a planning repo (`~/.beads-planning` by default)
|
||||
3. ✅ Configure auto-routing so your planning stays separate
|
||||
4. ✅ Initialize the planning repo with git
|
||||
|
||||
### Step 3: Start Working
|
||||
|
||||
```bash
|
||||
# Create a planning issue
|
||||
bd create "Plan how to fix bug X" -p 2
|
||||
|
||||
# This issue goes to ~/.beads-planning automatically!
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Auto-Routing
|
||||
|
||||
When you create issues as a contributor:
|
||||
|
||||
```bash
|
||||
bd create "Fix authentication bug" -p 1
|
||||
```
|
||||
|
||||
Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/beads.jsonl`), not the current repo.
|
||||
|
||||
### Viewing Issues
|
||||
|
||||
```bash
|
||||
# See all issues (from both repos)
|
||||
bd list
|
||||
|
||||
# See only current repo issues
|
||||
bd list --source-repo .
|
||||
|
||||
# See only planning issues
|
||||
bd list --source-repo ~/.beads-planning
|
||||
```
|
||||
|
||||
### Discovered Work
|
||||
|
||||
When you discover work while implementing:
|
||||
|
||||
```bash
|
||||
# The new issue inherits source_repo from parent
|
||||
bd create "Found edge case in auth" -p 1 --deps discovered-from:bd-42
|
||||
```
|
||||
|
||||
### Committing Code (Not Planning)
|
||||
|
||||
Your code changes get committed to the fork, but planning issues stay separate:
|
||||
|
||||
```bash
|
||||
# Only commits to fork (not planning repo)
|
||||
git add src/auth.go
|
||||
git commit -m "Fix: authentication bug"
|
||||
git push origin my-feature-branch
|
||||
```
|
||||
|
||||
Your planning issues in `~/.beads-planning` **never appear in PRs**.
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```bash
|
||||
# 1. Create fork and clone
|
||||
git clone https://github.com/you/upstream-project.git
|
||||
cd upstream-project
|
||||
git remote add upstream https://github.com/upstream/upstream-project.git
|
||||
|
||||
# 2. Run contributor setup
|
||||
bd init --contributor
|
||||
# Wizard detects fork ✓
|
||||
# Creates ~/.beads-planning ✓
|
||||
# Configures auto-routing ✓
|
||||
|
||||
# 3. Plan your work (routes to planning repo)
|
||||
bd create "Research how auth module works" -p 2
|
||||
bd create "Design fix for bug #123" -p 1
|
||||
bd ready # Shows planning issues
|
||||
|
||||
# 4. Implement (commit code only)
|
||||
git checkout -b fix-auth-bug
|
||||
# ... make changes ...
|
||||
git add . && git commit -m "Fix: auth bug"
|
||||
|
||||
# 5. Track discovered work (stays in planning repo)
|
||||
bd create "Found related issue in logout" -p 2 --deps discovered-from:bd-abc
|
||||
|
||||
# 6. Push code (planning never included)
|
||||
git push origin fix-auth-bug
|
||||
# Create PR on GitHub - zero planning pollution!
|
||||
|
||||
# 7. Clean up after PR merges
|
||||
bd close bd-abc --reason "PR merged"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The wizard configures these settings in `.beads/beads.db`:
|
||||
|
||||
```yaml
|
||||
contributor:
|
||||
planning_repo: ~/.beads-planning
|
||||
auto_route: true
|
||||
```
|
||||
|
||||
### Manual Configuration
|
||||
|
||||
If you prefer manual setup:
|
||||
|
||||
```bash
|
||||
# Initialize beads normally
|
||||
bd init
|
||||
|
||||
# Configure planning repo
|
||||
bd config set contributor.planning_repo ~/.beads-planning
|
||||
bd config set contributor.auto_route true
|
||||
```
|
||||
|
||||
## Multi-Repository View
|
||||
|
||||
Beads aggregates issues from multiple repos:
|
||||
|
||||
```bash
|
||||
# List issues from all configured repos
|
||||
bd list
|
||||
|
||||
# Filter by source repository
|
||||
bd list --source-repo . # Current repo only
|
||||
bd list --source-repo ~/.beads-planning # Planning repo only
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **Clean PRs** - No personal todos in upstream contributions
|
||||
✅ **Private planning** - Experimental work stays local
|
||||
✅ **Git ledger** - Everything is version controlled
|
||||
✅ **Unified view** - See all issues with `bd list`
|
||||
✅ **Auto-routing** - No manual sorting needed
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Q: What if I want some issues in the upstream repo?
|
||||
|
||||
A: Override auto-routing with `--source-repo` flag:
|
||||
|
||||
```bash
|
||||
bd create "Document new API" -p 2 --source-repo .
|
||||
```
|
||||
|
||||
### Q: Can I change the planning repo location?
|
||||
|
||||
A: Yes, configure it:
|
||||
|
||||
```bash
|
||||
bd config set contributor.planning_repo /path/to/my-planning
|
||||
```
|
||||
|
||||
### Q: What if I have push access to upstream?
|
||||
|
||||
A: The wizard will ask if you want a planning repo anyway. You can say "no" to store everything in the current repo.
|
||||
|
||||
### Q: How do I disable auto-routing?
|
||||
|
||||
A: Turn it off:
|
||||
|
||||
```bash
|
||||
bd config set contributor.auto_route false
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md)
|
||||
- [Team Workflow Example](../team-workflow/)
|
||||
- [Protected Branch Setup](../protected-branch/)
|
||||
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
|
||||
665
examples/multiple-personas/README.md
Normal file
665
examples/multiple-personas/README.md
Normal 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
|
||||
402
examples/team-workflow/README.md
Normal file
402
examples/team-workflow/README.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# Team Workflow Example
|
||||
|
||||
This example demonstrates how to use beads for team collaboration with shared repositories.
|
||||
|
||||
## Problem
|
||||
|
||||
When working as a team on a shared repository, you want to:
|
||||
- Track issues collaboratively
|
||||
- Keep everyone in sync via git
|
||||
- Handle protected main branches
|
||||
- Maintain clean git history
|
||||
|
||||
## Solution
|
||||
|
||||
Use `bd init --team` to set up team collaboration with automatic sync and optional protected branch support.
|
||||
|
||||
## Setup
|
||||
|
||||
### Step 1: Initialize Team Workflow
|
||||
|
||||
```bash
|
||||
# In your shared repository
|
||||
cd my-project
|
||||
|
||||
# Run the team setup wizard
|
||||
bd init --team
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
1. ✅ Detect your git configuration
|
||||
2. ✅ Ask if main branch is protected
|
||||
3. ✅ Configure sync branch (if needed)
|
||||
4. ✅ Set up automatic sync
|
||||
5. ✅ Enable team mode
|
||||
|
||||
### Step 2: Protected Branch Configuration
|
||||
|
||||
If your main branch is protected (GitHub/GitLab), the wizard will:
|
||||
- Create a separate `beads-metadata` branch for issue updates
|
||||
- Configure beads to commit to this branch automatically
|
||||
- Set up periodic PR workflow for merging to main
|
||||
|
||||
### Step 3: Team Members Join
|
||||
|
||||
Other team members just need to:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/org/project.git
|
||||
cd project
|
||||
|
||||
# Initialize beads (auto-imports existing issues)
|
||||
bd init
|
||||
|
||||
# Start working!
|
||||
bd ready
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Direct Commits (No Protected Branch)
|
||||
|
||||
If main isn't protected:
|
||||
|
||||
```bash
|
||||
# Create issue
|
||||
bd create "Implement feature X" -p 1
|
||||
|
||||
# Daemon auto-commits to main
|
||||
# (or run 'bd sync' manually)
|
||||
|
||||
# Pull to see team's issues
|
||||
git pull
|
||||
bd list
|
||||
```
|
||||
|
||||
### Protected Branch Workflow
|
||||
|
||||
If main is protected:
|
||||
|
||||
```bash
|
||||
# Create issue
|
||||
bd create "Implement feature X" -p 1
|
||||
|
||||
# Daemon commits to beads-metadata branch
|
||||
# (or run 'bd sync' manually)
|
||||
|
||||
# Push beads-metadata
|
||||
git push origin beads-metadata
|
||||
|
||||
# Periodically: merge beads-metadata to main via PR
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The wizard configures:
|
||||
|
||||
```yaml
|
||||
team:
|
||||
enabled: true
|
||||
sync_branch: beads-metadata # or main if not protected
|
||||
|
||||
daemon:
|
||||
auto_commit: true
|
||||
auto_push: true
|
||||
```
|
||||
|
||||
### Manual Configuration
|
||||
|
||||
```bash
|
||||
# Enable team mode
|
||||
bd config set team.enabled true
|
||||
|
||||
# Set sync branch
|
||||
bd config set team.sync_branch beads-metadata
|
||||
|
||||
# Enable auto-sync
|
||||
bd config set daemon.auto_commit true
|
||||
bd config set daemon.auto_push true
|
||||
```
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Scenario 1: Unprotected Main
|
||||
|
||||
```bash
|
||||
# Alice creates an issue
|
||||
bd create "Fix authentication bug" -p 1
|
||||
|
||||
# Daemon commits and pushes to main
|
||||
# (auto-sync enabled)
|
||||
|
||||
# Bob pulls changes
|
||||
git pull
|
||||
bd list # Sees Alice's issue
|
||||
|
||||
# Bob claims it
|
||||
bd update bd-abc --status in_progress
|
||||
|
||||
# Daemon commits Bob's update
|
||||
# Alice pulls and sees Bob is working on it
|
||||
```
|
||||
|
||||
### Scenario 2: Protected Main
|
||||
|
||||
```bash
|
||||
# Alice creates an issue
|
||||
bd create "Add new API endpoint" -p 1
|
||||
|
||||
# Daemon commits to beads-metadata
|
||||
git push origin beads-metadata
|
||||
|
||||
# Bob pulls beads-metadata
|
||||
git pull origin beads-metadata
|
||||
bd list # Sees Alice's issue
|
||||
|
||||
# Later: merge beads-metadata to main via PR
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git merge beads-metadata
|
||||
# Create PR, get approval, merge
|
||||
```
|
||||
|
||||
## Team Workflows
|
||||
|
||||
### Daily Standup
|
||||
|
||||
```bash
|
||||
# See what everyone's working on
|
||||
bd list --status in_progress
|
||||
|
||||
# See what's ready for work
|
||||
bd ready
|
||||
|
||||
# See recently closed issues
|
||||
bd list --status closed --limit 10
|
||||
```
|
||||
|
||||
### Sprint Planning
|
||||
|
||||
```bash
|
||||
# Create sprint issues
|
||||
bd create "Implement user auth" -p 1
|
||||
bd create "Add profile page" -p 1
|
||||
bd create "Fix responsive layout" -p 2
|
||||
|
||||
# Assign to team members
|
||||
bd update bd-abc --assignee alice
|
||||
bd update bd-def --assignee bob
|
||||
|
||||
# Track dependencies
|
||||
bd dep add bd-def bd-abc --type blocks
|
||||
```
|
||||
|
||||
### PR Integration
|
||||
|
||||
```bash
|
||||
# Create issue for PR work
|
||||
bd create "Refactor auth module" -p 1
|
||||
|
||||
# Work on it
|
||||
bd update bd-abc --status in_progress
|
||||
|
||||
# Open PR with issue reference
|
||||
git push origin feature-branch
|
||||
# PR title: "feat: refactor auth module (bd-abc)"
|
||||
|
||||
# Close when PR merges
|
||||
bd close bd-abc --reason "PR #123 merged"
|
||||
```
|
||||
|
||||
## Sync Strategies
|
||||
|
||||
### Auto-Sync (Recommended)
|
||||
|
||||
Daemon commits and pushes automatically:
|
||||
|
||||
```bash
|
||||
bd daemon start --auto-commit --auto-push
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- ✅ Always in sync
|
||||
- ✅ No manual intervention
|
||||
- ✅ Real-time collaboration
|
||||
|
||||
### Manual Sync
|
||||
|
||||
Sync when you want:
|
||||
|
||||
```bash
|
||||
bd sync # Export, commit, pull, import, push
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- ✅ Full control
|
||||
- ✅ Batch updates
|
||||
- ✅ Review before push
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
Hash-based IDs prevent most conflicts. If conflicts occur:
|
||||
|
||||
```bash
|
||||
# During git pull/merge
|
||||
git pull origin beads-metadata
|
||||
# CONFLICT in .beads/beads.jsonl
|
||||
|
||||
# Option 1: Accept remote
|
||||
git checkout --theirs .beads/beads.jsonl
|
||||
bd import -i .beads/beads.jsonl
|
||||
|
||||
# Option 2: Accept local
|
||||
git checkout --ours .beads/beads.jsonl
|
||||
bd import -i .beads/beads.jsonl
|
||||
|
||||
# Option 3: Use beads-merge tool (recommended)
|
||||
# See AGENTS.md for beads-merge integration
|
||||
|
||||
git add .beads/beads.jsonl
|
||||
git commit
|
||||
```
|
||||
|
||||
## Protected Branch Best Practices
|
||||
|
||||
### For Protected Main:
|
||||
|
||||
1. **Create beads-metadata branch**
|
||||
```bash
|
||||
git checkout -b beads-metadata
|
||||
git push origin beads-metadata
|
||||
```
|
||||
|
||||
2. **Configure protection rules**
|
||||
- Allow direct pushes to beads-metadata
|
||||
- Require PR for main
|
||||
|
||||
3. **Periodic PR workflow**
|
||||
```bash
|
||||
# Once per day/sprint
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout beads-metadata
|
||||
git pull origin beads-metadata
|
||||
git checkout main
|
||||
git merge beads-metadata
|
||||
# Create PR, get approval, merge
|
||||
```
|
||||
|
||||
4. **Keep beads-metadata clean**
|
||||
```bash
|
||||
# After PR merges
|
||||
git checkout beads-metadata
|
||||
git rebase main
|
||||
git push origin beads-metadata --force-with-lease
|
||||
```
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Q: How do team members see each other's issues?
|
||||
|
||||
A: Issues are stored in `.beads/beads.jsonl` which is version-controlled. Pull from git to sync.
|
||||
|
||||
```bash
|
||||
git pull
|
||||
bd list # See everyone's issues
|
||||
```
|
||||
|
||||
### Q: What if two people create issues at the same time?
|
||||
|
||||
A: Hash-based IDs prevent collisions. Even if created simultaneously, they get different IDs.
|
||||
|
||||
### Q: How do I disable auto-sync?
|
||||
|
||||
A: Turn it off:
|
||||
|
||||
```bash
|
||||
bd config set daemon.auto_commit false
|
||||
bd config set daemon.auto_push false
|
||||
|
||||
# Sync manually
|
||||
bd sync
|
||||
```
|
||||
|
||||
### Q: Can we use different sync branches per person?
|
||||
|
||||
A: Not recommended. Use a single shared branch for consistency. If needed:
|
||||
|
||||
```bash
|
||||
bd config set sync.branch my-custom-branch
|
||||
```
|
||||
|
||||
### Q: What about CI/CD integration?
|
||||
|
||||
A: Add to your CI pipeline:
|
||||
|
||||
```bash
|
||||
# In .github/workflows/main.yml
|
||||
- name: Sync beads issues
|
||||
run: |
|
||||
bd sync
|
||||
git push origin beads-metadata
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Daemon not committing
|
||||
|
||||
Check daemon status:
|
||||
|
||||
```bash
|
||||
bd daemon status
|
||||
bd daemons list
|
||||
```
|
||||
|
||||
Verify config:
|
||||
|
||||
```bash
|
||||
bd config get daemon.auto_commit
|
||||
bd config get daemon.auto_push
|
||||
```
|
||||
|
||||
Restart daemon:
|
||||
|
||||
```bash
|
||||
bd daemon stop
|
||||
bd daemon start --auto-commit --auto-push
|
||||
```
|
||||
|
||||
### Issue: Merge conflicts in JSONL
|
||||
|
||||
Use beads-merge (see [AGENTS.md](../../AGENTS.md#advanced-intelligent-merge-tools)) or resolve manually:
|
||||
|
||||
```bash
|
||||
git checkout --theirs .beads/beads.jsonl
|
||||
bd import -i .beads/beads.jsonl
|
||||
git add .beads/beads.jsonl
|
||||
git commit
|
||||
```
|
||||
|
||||
### Issue: Issues not syncing
|
||||
|
||||
Manually sync:
|
||||
|
||||
```bash
|
||||
bd sync
|
||||
git push
|
||||
```
|
||||
|
||||
Check for conflicts:
|
||||
|
||||
```bash
|
||||
git status
|
||||
bd validate --checks=conflicts
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Protected Branch Setup](../protected-branch/)
|
||||
- [Contributor Workflow](../contributor-workflow/)
|
||||
- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md)
|
||||
- [Advanced Merge Tools](../../AGENTS.md#advanced-intelligent-merge-tools)
|
||||
Reference in New Issue
Block a user