johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive protected branch workflow documentation (bd-5ce8)

Browse Source 
Created complete documentation suite for using beads with protected branches:

1. **docs/PROTECTED_BRANCHES.md** - Comprehensive 600+ line guide covering:
   - Quick start and setup
   - How git worktrees work
   - Daily workflow for agents and humans
   - Merging strategies (PR and direct)
   - Troubleshooting common issues
   - Platform-specific notes (GitHub, GitLab, Bitbucket)
   - Advanced topics (CI/CD, multi-clone sync, etc.)

2. **AGENTS.md** - Added "Protected Branch Workflow" section:
   - Quick reference for agents
   - No changes needed to agent workflows
   - Commands for setup and merging
   - Link to detailed docs

3. **README.md** - Updated with:
   - Protected branch support feature flag
   - Quick start instructions with --branch flag
   - Link to comprehensive guide

4. **examples/protected-branch/** - Working example with:
   - Step-by-step demo
   - Multi-clone sync workflow
   - GitHub Actions integration example
   - Directory structure explanation
   - Troubleshooting tips

All commands verified:
- bd init --branch <name>
- bd config get/set sync.branch
- bd sync --status
- bd sync --merge

Documentation is platform-agnostic and works with GitHub, GitLab,
Bitbucket, or any git platform with branch protection.

Closes bd-5ce8

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-02 18:41:25 -08:00
parent 9f9167c5db
commit edf1f71fa7
5 changed files with 1025 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@@ -57,6 +57,7 @@ Agents report that they enjoy working with Beads, and they will use it spontaneo
- 🤖 **Agent-friendly** - `--json` flags for programmatic integration
- 📦 **Git-versioned** - JSONL records stored in git, synced across machines
- 🌍 **Distributed by design** - Agents on multiple machines share one logical database via git
- 🔐 **Protected branch support** - Works with GitHub/GitLab protected branches via separate sync branch
- 🏗️ **Extensible** - Add your own tables to the SQLite database
- 🔍 **Multi-project isolation** - Each project gets its own database, auto-discovered by directory
- 🌲 **Dependency trees** - Visualize full dependency graphs
@@ -93,6 +94,9 @@ Beads is designed for **AI coding agents** to use on your behalf. Setup takes 30
# In your project root:
bd init
# For protected branches (GitHub/GitLab):
bd init --branch beads-metadata
# bd will:
# - Create .beads/ directory with database
# - Import existing issues from git (if any)
@@ -103,6 +107,8 @@ bd init
echo "BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instructions" >> AGENTS.md
```
**Protected branches?** If your `main` branch is protected, use `bd init --branch beads-metadata` to commit issue updates to a separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md) for details.
**Your agent does the rest:** Next time your agent starts, it will:
1. Run `bd onboard` and receive integration instructions
2. Add bd workflow documentation to AGENTS.md