beads/examples/team-workflow/README.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

394 lines
7.2 KiB
Markdown

# 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
# Dolt server auto-commits to main
# (or run 'bd dolt push' 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
# Auto-commits to beads-metadata branch
# (or run 'bd dolt push' 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
dolt:
auto-commit: on
```
### 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-commit
bd config set dolt.auto-commit on
```
## Example Workflows
### Scenario 1: Unprotected Main
```bash
# 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 --claim
# Auto-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
# 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
```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 --claim
# 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)
The Dolt server commits and pushes automatically when auto-commit is enabled:
```bash
bd config set dolt.auto-commit on
bd dolt start
```
Benefits:
- ✅ Always in sync
- ✅ No manual intervention
- ✅ Real-time collaboration
### Manual Sync
Push and pull when you want:
```bash
bd dolt push # Push local changes to remote
bd dolt pull # Pull remote changes locally
```
Benefits:
- ✅ Full control
- ✅ Batch updates
- ✅ Review before push
## Conflict Resolution
Hash-based IDs prevent most conflicts. Dolt handles merges natively using three-way merge, similar to git. If conflicts occur during `bd dolt pull`:
```bash
# View conflicts
bd sql "SELECT * FROM dolt_conflicts"
# Resolve by accepting ours or theirs
bd sql "CALL dolt_conflicts_resolve('--ours')"
# OR
bd sql "CALL dolt_conflicts_resolve('--theirs')"
# Complete the sync
bd dolt push
```
## 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 Dolt, which supports distributed sync. Use `bd dolt pull` to fetch and `bd dolt push` to share changes.
```bash
bd dolt 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 dolt.auto-commit off
# Sync manually
bd dolt push
bd dolt pull
```
### 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 dolt push
git push origin beads-metadata
```
## Troubleshooting
### Issue: Server not committing
Check server status:
```bash
bd doctor
```
Verify config:
```bash
bd config get dolt.auto-commit
```
Restart Dolt server:
```bash
bd dolt stop
bd dolt start
```
### Issue: Merge conflicts
Dolt handles merges natively. If conflicts occur during sync:
```bash
bd sql "SELECT * FROM dolt_conflicts"
bd sql "CALL dolt_conflicts_resolve('--ours')"
bd dolt push
```
See [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md) for details.
### Issue: Issues not syncing
Manually sync:
```bash
bd dolt push
bd dolt pull
```
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)
- [Git Integration Guide](../../docs/GIT_INTEGRATION.md)