beads/examples/team-workflow
topaz 062aedbed7 docs: remove stale daemon references from all documentation (GH#1982)
Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/,
integrations/, and root to replace removed `bd daemon` references with
current Dolt server mode equivalents. CHANGELOG.md preserved per policy.

Key replacements:
- `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor`
- `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor`
- `--no-daemon` flag → removed (embedded mode is default)
- `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed
- `.beads/bd.sock` → removed
- "daemon mode" / "direct mode" → "server mode" / "embedded mode"
- daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/polecats/topaz
Rig: beads
Role: polecats
2026-02-22 17:57:53 -08:00
..
README.md docs: remove stale daemon references from all documentation (GH#1982) 2026-02-22 17:57:53 -08:00

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

# 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:

# 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:

# Create issue
bd create "Implement feature X" -p 1

# Dolt server 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:

# Create issue
bd create "Implement feature X" -p 1

# Auto-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:

team:
  enabled: true
  sync_branch: beads-metadata  # or main if not protected

dolt:
  auto-commit: on

Manual Configuration

# Enable team mode
bd config set team.enabled true

# Set sync branch
bd config set team.sync_branch beads-metadata

# Enable auto-commit
bd config set dolt.auto-commit on

Example Workflows

Scenario 1: Unprotected Main

# Alice creates an issue
bd create "Fix authentication bug" -p 1

# Auto-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

# Auto-commits Bob's update
# Alice pulls and sees Bob is working on it

Scenario 2: Protected Main

# Alice creates an issue
bd create "Add new API endpoint" -p 1

# Auto-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

# 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

# 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

# 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

The Dolt server commits and pushes automatically when auto-commit is enabled:

bd config set dolt.auto-commit on
bd dolt start

Benefits:

  • ✅ Always in sync
  • ✅ No manual intervention
  • ✅ Real-time collaboration

Manual Sync

Sync when you want:

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:

# During git pull/merge
git pull origin beads-metadata
# CONFLICT in .beads/issues.jsonl

# Option 1: Accept remote
git checkout --theirs .beads/issues.jsonl
bd import -i .beads/issues.jsonl

# Option 2: Accept local
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl

# Option 3: Use beads-merge tool (recommended)
# See docs/GIT_INTEGRATION.md for merge conflict resolution

git add .beads/issues.jsonl
git commit

Protected Branch Best Practices

For Protected Main:

  1. Create beads-metadata branch

    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

    # 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

    # 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/issues.jsonl which is version-controlled. Pull from git to sync.

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:

bd config set dolt.auto-commit off

# 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:

bd config set sync.branch my-custom-branch

Q: What about CI/CD integration?

A: Add to your CI pipeline:

# In .github/workflows/main.yml
- name: Sync beads issues
  run: |
    bd sync
    git push origin beads-metadata

Troubleshooting

Issue: Server not committing

Check server status:

bd doctor

Verify config:

bd config get dolt.auto-commit

Restart Dolt server:

bd dolt stop
bd dolt start

Issue: Merge conflicts in JSONL

Use beads-merge or resolve manually (see GIT_INTEGRATION.md):

git checkout --theirs .beads/issues.jsonl
bd import -i .beads/issues.jsonl
git add .beads/issues.jsonl
git commit

Issue: Issues not syncing

Manually sync:

bd sync
git push

Check for conflicts:

git status
bd validate --checks=conflicts

See Also