Add multi-repo patterns documentation for AI agents (bd-4b6u)
- Create docs/MULTI_REPO_AGENTS.md with comprehensive multi-repo patterns - Document config options, routing behavior, troubleshooting, best practices - Update AGENTS.md to reference new doc - Update README.md documentation index Amp-Thread-ID: https://ampcode.com/threads/T-645ccbf4-a5b6-44a1-bbd9-913447e17b49 Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
@@ -62,6 +62,8 @@ See `integrations/beads-mcp/README.md` for complete documentation.
|
||||
|
||||
**RECOMMENDED: Use a single MCP server for all beads projects** - it automatically routes to per-project local daemons.
|
||||
|
||||
**For AI agent multi-repo patterns**, see [docs/MULTI_REPO_AGENTS.md](docs/MULTI_REPO_AGENTS.md) (config options, routing, troubleshooting, best practices).
|
||||
|
||||
**For complete multi-repo workflow guide**, see [docs/MULTI_REPO_MIGRATION.md](docs/MULTI_REPO_MIGRATION.md) (OSS contributors, teams, multi-phase development).
|
||||
|
||||
**Setup (one-time):**
|
||||
|
||||
@@ -675,6 +675,7 @@ For advanced usage, see:
|
||||
- **[INSTALLING.md](INSTALLING.md)** - Complete installation guide for all platforms
|
||||
- **[QUICKSTART.md](QUICKSTART.md)** - Interactive tutorial (`bd quickstart`)
|
||||
- **[docs/MULTI_REPO_MIGRATION.md](docs/MULTI_REPO_MIGRATION.md)** - Multi-repo workflow guide (OSS, teams, multi-phase)
|
||||
- **[docs/MULTI_REPO_AGENTS.md](docs/MULTI_REPO_AGENTS.md)** - Multi-repo patterns for AI agents
|
||||
- **[FAQ.md](FAQ.md)** - Frequently asked questions
|
||||
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
|
||||
- **[ADVANCED.md](ADVANCED.md)** - Advanced features and use cases
|
||||
|
||||
416
docs/MULTI_REPO_AGENTS.md
Normal file
416
docs/MULTI_REPO_AGENTS.md
Normal file
@@ -0,0 +1,416 @@
|
||||
# Multi-Repo Patterns for AI Agents
|
||||
|
||||
This guide covers multi-repo workflow patterns specifically for AI agents working with beads.
|
||||
|
||||
**For humans**, see [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for interactive wizards and detailed setup.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Single MCP Server (Recommended)
|
||||
|
||||
AI agents should use **one MCP server instance** that automatically routes to per-project daemons:
|
||||
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The MCP server automatically:
|
||||
- Detects current workspace from working directory
|
||||
- Routes to correct per-project daemon (`.beads/bd.sock`)
|
||||
- Auto-starts daemon if not running
|
||||
- Maintains complete database isolation
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
MCP Server (one instance)
|
||||
↓
|
||||
Per-Project Daemons (one per workspace)
|
||||
↓
|
||||
SQLite Databases (complete isolation)
|
||||
```
|
||||
|
||||
### Multi-Repo Config Options
|
||||
|
||||
Agents can configure multi-repo behavior via `bd config`:
|
||||
|
||||
```bash
|
||||
# Auto-routing (detects role: maintainer vs contributor)
|
||||
bd config set routing.mode auto
|
||||
bd config set routing.maintainer "."
|
||||
bd config set routing.contributor "~/.beads-planning"
|
||||
|
||||
# Explicit routing (always use default)
|
||||
bd config set routing.mode explicit
|
||||
bd config set routing.default "."
|
||||
|
||||
# Multi-repo aggregation (hydration)
|
||||
bd config set repos.primary "."
|
||||
bd config set repos.additional "~/repo1,~/repo2,~/repo3"
|
||||
```
|
||||
|
||||
**Check current config:**
|
||||
```bash
|
||||
bd config get routing.mode
|
||||
bd config get repos.additional
|
||||
bd info --json # Shows all config
|
||||
```
|
||||
|
||||
## Routing Behavior
|
||||
|
||||
### Auto-Routing (OSS Contributor Pattern)
|
||||
|
||||
When `routing.mode=auto`, beads detects user role and routes new issues automatically:
|
||||
|
||||
**Maintainer (SSH push access):**
|
||||
```bash
|
||||
# Git remote: git@github.com:user/repo.git
|
||||
bd create "Fix bug" -p 1
|
||||
# → Creates in current repo (source_repo = ".")
|
||||
```
|
||||
|
||||
**Contributor (HTTPS or no push access):**
|
||||
```bash
|
||||
# Git remote: https://github.com/fork/repo.git
|
||||
bd create "Fix bug" -p 1
|
||||
# → Creates in planning repo (source_repo = "~/.beads-planning")
|
||||
```
|
||||
|
||||
**Role detection priority:**
|
||||
1. Explicit git config: `git config beads.role maintainer|contributor`
|
||||
2. Git remote URL inspection (SSH = maintainer, HTTPS = contributor)
|
||||
3. Fallback: contributor
|
||||
|
||||
### Explicit Override
|
||||
|
||||
Always available regardless of routing mode:
|
||||
|
||||
```bash
|
||||
# Force creation in specific repo
|
||||
bd create "Issue" -p 1 --repo /path/to/repo
|
||||
bd create "Issue" -p 1 --repo ~/my-planning
|
||||
```
|
||||
|
||||
### Discovered Issue Inheritance
|
||||
|
||||
Issues with `discovered-from` dependencies automatically inherit parent's `source_repo`:
|
||||
|
||||
```bash
|
||||
# Parent in current repo
|
||||
bd create "Implement auth" -p 1
|
||||
# → Created as bd-abc (source_repo = ".")
|
||||
|
||||
# Discovered issue inherits parent's repo
|
||||
bd create "Found bug" -p 1 --deps discovered-from:bd-abc
|
||||
# → Created with source_repo = "." (same as parent)
|
||||
```
|
||||
|
||||
**Override if needed:**
|
||||
```bash
|
||||
bd create "Issue" -p 1 --deps discovered-from:bd-abc --repo /different/repo
|
||||
```
|
||||
|
||||
## Multi-Repo Hydration
|
||||
|
||||
Agents working in multi-repo mode see aggregated issues from multiple repositories:
|
||||
|
||||
```bash
|
||||
# View all issues (current + additional repos)
|
||||
bd ready --json
|
||||
bd list --json
|
||||
|
||||
# Filter by source repository
|
||||
bd list --json | jq '.[] | select(.source_repo == ".")'
|
||||
bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")'
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. Beads reads JSONL from all configured repos
|
||||
2. Imports into unified SQLite database
|
||||
3. Maintains `source_repo` field for provenance
|
||||
4. Exports route issues back to correct JSONL files
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### OSS Contributor Workflow
|
||||
|
||||
**Setup:** Human runs `bd init --contributor` (wizard handles config)
|
||||
|
||||
**Agent workflow:**
|
||||
```bash
|
||||
# All planning issues auto-route to separate repo
|
||||
bd create "Investigate implementation" -p 1
|
||||
bd create "Draft RFC" -p 2
|
||||
# → Created in ~/.beads-planning (never appears in PRs)
|
||||
|
||||
# View all work (upstream + planning)
|
||||
bd ready
|
||||
bd list --json
|
||||
|
||||
# Complete work
|
||||
bd close plan-42 --reason "Done"
|
||||
|
||||
# Git commit/push - no .beads/ pollution in PR ✅
|
||||
```
|
||||
|
||||
### Team Workflow
|
||||
|
||||
**Setup:** Human runs `bd init --team` (wizard handles config)
|
||||
|
||||
**Agent workflow:**
|
||||
```bash
|
||||
# Shared team planning (committed to repo)
|
||||
bd create "Implement feature X" -p 1
|
||||
# → Created in current repo (visible to team)
|
||||
|
||||
# Optional: Personal experiments in separate repo
|
||||
bd create "Try alternative" -p 2 --repo ~/.beads-planning-personal
|
||||
# → Created in personal repo (private)
|
||||
|
||||
# View all
|
||||
bd ready --json
|
||||
```
|
||||
|
||||
### Multi-Phase Development
|
||||
|
||||
**Setup:** Multiple repos for different phases
|
||||
|
||||
**Agent workflow:**
|
||||
```bash
|
||||
# Phase 1: Planning repo
|
||||
cd ~/projects/myapp-planning
|
||||
bd create "Design auth" -p 1 -t epic
|
||||
|
||||
# Phase 2: Implementation repo (views planning + impl)
|
||||
cd ~/projects/myapp-implementation
|
||||
bd ready # Shows both repos
|
||||
bd create "Implement auth backend" -p 1
|
||||
bd dep add impl-42 plan-10 --type blocks # Link across repos
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issues appearing in wrong repository
|
||||
|
||||
**Symptom:** `bd create` routes to unexpected repo
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
bd config get routing.mode
|
||||
bd config get routing.maintainer
|
||||
bd config get routing.contributor
|
||||
bd info --json | jq '.role'
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Use explicit flag
|
||||
bd create "Issue" -p 1 --repo .
|
||||
|
||||
# Or reconfigure routing
|
||||
bd config set routing.mode explicit
|
||||
bd config set routing.default "."
|
||||
```
|
||||
|
||||
### Can't see issues from other repos
|
||||
|
||||
**Symptom:** `bd list` only shows current repo
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
bd config get repos.additional
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Add missing repos
|
||||
bd config set repos.additional "~/repo1,~/repo2"
|
||||
|
||||
# Force sync
|
||||
bd sync
|
||||
bd list --json
|
||||
```
|
||||
|
||||
### Discovered issues in wrong repository
|
||||
|
||||
**Symptom:** Issues with `discovered-from` appear in wrong repo
|
||||
|
||||
**Explanation:** This is intentional - discovered issues inherit parent's `source_repo`
|
||||
|
||||
**Override if needed:**
|
||||
```bash
|
||||
bd create "Issue" -p 1 --deps discovered-from:bd-42 --repo /different/repo
|
||||
```
|
||||
|
||||
### Planning repo polluting PRs
|
||||
|
||||
**Symptom:** `~/.beads-planning` changes appear in upstream PRs
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
# Planning repo should be separate
|
||||
ls -la ~/.beads-planning/.git # Should exist
|
||||
|
||||
# Fork should NOT contain planning issues
|
||||
cd ~/projects/fork
|
||||
bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")'
|
||||
# Should be empty
|
||||
|
||||
# Check routing
|
||||
bd config get routing.contributor # Should be ~/.beads-planning
|
||||
```
|
||||
|
||||
### Daemon routing to wrong database
|
||||
|
||||
**Symptom:** MCP operations affect wrong project
|
||||
|
||||
**Cause:** Using multiple MCP server instances (not recommended)
|
||||
|
||||
**Fix:**
|
||||
```json
|
||||
// RECOMMENDED: Single MCP server
|
||||
{
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The single MCP server automatically routes based on workspace directory.
|
||||
|
||||
### Version mismatch after upgrade
|
||||
|
||||
**Symptom:** Daemon operations fail after `bd` upgrade
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
bd daemons health --json # Check for mismatches
|
||||
bd daemons killall # Restart all daemons
|
||||
# Daemons auto-start with new version on next command
|
||||
```
|
||||
|
||||
## Best Practices for Agents
|
||||
|
||||
### OSS Contributors
|
||||
- ✅ Planning issues auto-route to `~/.beads-planning`
|
||||
- ✅ Never commit `.beads/` in PRs to upstream
|
||||
- ✅ Use `bd ready` to see all work (upstream + planning)
|
||||
- ❌ Don't manually override routing without good reason
|
||||
|
||||
### Teams
|
||||
- ✅ Commit `.beads/beads.jsonl` to shared repo
|
||||
- ✅ Use `bd sync` to ensure changes are committed/pushed
|
||||
- ✅ Link related issues across repos with dependencies
|
||||
- ❌ Don't gitignore `.beads/` - you lose the git ledger
|
||||
|
||||
### Multi-Phase Projects
|
||||
- ✅ Use clear repo names (`planning`, `impl`, `maint`)
|
||||
- ✅ Link issues across phases with `blocks` dependencies
|
||||
- ✅ Use `bd list --json` to filter by `source_repo`
|
||||
- ❌ Don't duplicate issues across repos
|
||||
|
||||
### General
|
||||
- ✅ Always use single MCP server (per-project daemons)
|
||||
- ✅ Check routing config before filing issues
|
||||
- ✅ Use `bd info --json` to verify workspace state
|
||||
- ✅ Run `bd sync` at end of session
|
||||
- ❌ Don't assume routing behavior - check config
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
Multi-repo mode is fully backward compatible:
|
||||
|
||||
**Without multi-repo config:**
|
||||
```bash
|
||||
bd create "Issue" -p 1
|
||||
# → Creates in .beads/beads.jsonl (single-repo mode)
|
||||
```
|
||||
|
||||
**With multi-repo config:**
|
||||
```bash
|
||||
bd create "Issue" -p 1
|
||||
# → Auto-routed based on config
|
||||
# → Old issues in .beads/beads.jsonl still work
|
||||
```
|
||||
|
||||
**Disabling multi-repo:**
|
||||
```bash
|
||||
bd config unset routing.mode
|
||||
bd config unset repos.additional
|
||||
# → Back to single-repo mode
|
||||
```
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Routing Config
|
||||
|
||||
```bash
|
||||
# Auto-detect role (maintainer vs contributor)
|
||||
bd config set routing.mode auto
|
||||
bd config set routing.maintainer "." # Where maintainer issues go
|
||||
bd config set routing.contributor "~/.beads-planning" # Where contributor issues go
|
||||
|
||||
# Explicit mode (always use default)
|
||||
bd config set routing.mode explicit
|
||||
bd config set routing.default "." # All issues go here
|
||||
|
||||
# Check settings
|
||||
bd config get routing.mode
|
||||
bd config get routing.maintainer
|
||||
bd config get routing.contributor
|
||||
bd config get routing.default
|
||||
```
|
||||
|
||||
### Multi-Repo Hydration
|
||||
|
||||
```bash
|
||||
# Set primary repo (optional, default is current)
|
||||
bd config set repos.primary "."
|
||||
|
||||
# Add additional repos to aggregate
|
||||
bd config set repos.additional "~/repo1,~/repo2,~/repo3"
|
||||
|
||||
# Check settings
|
||||
bd config get repos.primary
|
||||
bd config get repos.additional
|
||||
```
|
||||
|
||||
### Verify Configuration
|
||||
|
||||
```bash
|
||||
# Show all config + database path + daemon status
|
||||
bd info --json
|
||||
|
||||
# Sample output:
|
||||
{
|
||||
"database_path": "/Users/you/projects/myapp/.beads/beads.db",
|
||||
"config": {
|
||||
"routing": {
|
||||
"mode": "auto",
|
||||
"maintainer": ".",
|
||||
"contributor": "~/.beads-planning"
|
||||
},
|
||||
"repos": {
|
||||
"primary": ".",
|
||||
"additional": ["~/repo1", "~/repo2"]
|
||||
}
|
||||
},
|
||||
"daemon": {
|
||||
"running": true,
|
||||
"pid": 12345,
|
||||
"socket": ".beads/bd.sock"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md)** - Complete guide for humans with interactive wizards
|
||||
- **[ROUTING.md](ROUTING.md)** - Technical details of routing implementation
|
||||
- **[MULTI_REPO_HYDRATION.md](MULTI_REPO_HYDRATION.md)** - Hydration layer internals
|
||||
- **[AGENTS.md](../AGENTS.md)** - Main AI agent guide
|
||||
Reference in New Issue
Block a user