diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md deleted file mode 100644 index e051568f6..000000000 --- a/docs/ADVANCED.md +++ /dev/null @@ -1,332 +0,0 @@ -# Advanced bd Features - -This guide covers advanced features for power users and specific use cases. - -## Table of Contents - -- [Renaming Prefix](#renaming-prefix) -- [Merging Duplicate Issues](#merging-duplicate-issues) -- [Git Worktrees](#git-worktrees) -- [Database Redirects](#database-redirects) -- [Handling Import Collisions](#handling-import-collisions) -- [Custom Git Hooks](#custom-git-hooks) -- [Extensible Database](#extensible-database) -- [Architecture: Storage, RPC, and MCP](#architecture-storage-rpc-and-mcp) - -## Renaming Prefix - -Change the issue prefix for all issues in your database. This is useful if your prefix is too long or you want to standardize naming. - -```bash -# Preview changes without applying -bd rename-prefix kw- --dry-run - -# Rename from current prefix to new prefix -bd rename-prefix kw- - -# JSON output -bd rename-prefix kw- --json -``` - -The rename operation: -- Updates all issue IDs (e.g., `knowledge-work-1` β†’ `kw-1`) -- Updates all text references in titles, descriptions, design notes, etc. -- Updates dependencies and labels -- Updates the counter table and config - -**Prefix validation rules:** -- Max length: 8 characters -- Allowed characters: lowercase letters, numbers, hyphens -- Must start with a letter -- Must end with a hyphen (or will be trimmed to add one) -- Cannot be empty or just a hyphen - -Example workflow: -```bash -# You have issues like knowledge-work-1, knowledge-work-2, etc. -bd list # Shows knowledge-work-* issues - -# Preview the rename -bd rename-prefix kw- --dry-run - -# Apply the rename -bd rename-prefix kw- - -# Now you have kw-1, kw-2, etc. -bd list # Shows kw-* issues -``` - -## Duplicate Detection - -Find issues with identical content using automated duplicate detection: - -```bash -# Find all content duplicates in the database -bd duplicates - -# Show duplicates in JSON format -bd duplicates --json - -# Automatically merge all duplicates -bd duplicates --auto-merge - -# Preview what would be merged -bd duplicates --dry-run - -# Detect duplicates after initializing from JSONL -bd init --from-jsonl # then: bd duplicates -``` - -**How it works:** -- Groups issues by content hash (title, description, design, acceptance criteria) -- Only groups issues with matching status (open with open, closed with closed) -- Chooses merge target by reference count (most referenced) or smallest ID -- Reports duplicate groups with suggested merge commands - -**Example output:** - -``` -πŸ” Found 3 duplicate group(s): - -━━ Group 1: Fix authentication bug -β†’ bd-10 (open, P1, 5 references) - bd-42 (open, P1, 0 references) - Suggested: bd merge bd-42 --into bd-10 - -πŸ’‘ Run with --auto-merge to execute all suggested merges -``` - -**AI Agent Workflow:** - -1. **Periodic scans**: Run `bd duplicates` to check for duplicates -2. **During import**: Use `--dedupe-after` to detect duplicates after collision resolution -3. **Auto-merge**: Use `--auto-merge` to automatically consolidate duplicates -4. **Manual review**: Use `--dry-run` to preview merges before executing - -## Merging Duplicate Issues - -Consolidate duplicate issues into a single issue while preserving dependencies and references: - -```bash -# Merge bd-42 and bd-43 into bd-41 -bd merge bd-42 bd-43 --into bd-41 - -# Merge multiple duplicates at once -bd merge bd-10 bd-11 bd-12 --into bd-10 - -# Preview merge without making changes -bd merge bd-42 bd-43 --into bd-41 --dry-run - -# JSON output -bd merge bd-42 bd-43 --into bd-41 --json -``` - -**What the merge command does:** -1. **Validates** all issues exist and prevents self-merge -2. **Closes** source issues with reason `Merged into bd-X` -3. **Migrates** all dependencies from source issues to target -4. **Updates** text references across all issue descriptions, notes, design, and acceptance criteria - -**Example workflow:** - -```bash -# You discover bd-42 and bd-43 are duplicates of bd-41 -bd show bd-41 bd-42 bd-43 - -# Preview the merge -bd merge bd-42 bd-43 --into bd-41 --dry-run - -# Execute the merge -bd merge bd-42 bd-43 --into bd-41 -# βœ“ Merged 2 issue(s) into bd-41 - -# Verify the result -bd show bd-41 # Now has dependencies from bd-42 and bd-43 -bd dep tree bd-41 # Shows unified dependency tree -``` - -**Important notes:** -- Source issues are permanently closed (status: `closed`) -- All dependencies pointing to source issues are redirected to target -- Text references like "see bd-42" are automatically rewritten to "see bd-41" -- Operation cannot be undone (but git history preserves the original state) -**AI Agent Workflow:** - -When agents discover duplicate issues, they should: -1. Search for similar issues: `bd list --json | grep "similar text"` -2. Compare issue details: `bd show bd-41 bd-42 --json` -3. Merge duplicates: `bd merge bd-42 --into bd-41` -4. File a discovered-from issue if needed: `bd create "Found duplicates during bd-X" --deps discovered-from:bd-X` - -## Git Worktrees - -Git worktrees work with bd. Each worktree can have its own `.beads` directory, or worktrees can share a database via redirects (see [Database Redirects](#database-redirects)). - -**With Dolt backend:** Each worktree operates directly on the database β€” no special coordination needed. Use `bd dolt push` to sync with Dolt remotes when ready. - -**With Dolt server mode:** Multiple worktrees can connect to the same Dolt server for concurrent access without conflicts. - -## Database Redirects - -Multiple git clones can share a single beads database using redirect files. This is useful for: -- Multi-agent setups where several clones work on the same issues -- Development environments with multiple checkout directories -- Avoiding duplicate databases across clones - -### Setting Up a Redirect - -Create a `.beads/redirect` file pointing to the shared database location: - -```bash -# In your secondary clone -mkdir -p .beads -echo "../main-clone/.beads" > .beads/redirect - -# Or use an absolute path -echo "/path/to/shared/.beads" > .beads/redirect -``` - -The redirect file should contain a single path (relative or absolute) to the target `.beads` directory. - -**Example setup:** -``` -repo/ -β”œβ”€β”€ main-clone/ -β”‚ └── .beads/ -β”‚ └── beads.db ← Actual database -β”œβ”€β”€ agent-1/ -β”‚ └── .beads/ -β”‚ └── redirect ← Points to ../main-clone/.beads -└── agent-2/ - └── .beads/ - └── redirect ← Points to ../main-clone/.beads -``` - -### Checking Active Location - -Use `bd where` to see which database is actually being used: - -```bash -bd where -# /path/to/main-clone/.beads -# (via redirect from /path/to/agent-1/.beads) -# prefix: bd -# database: /path/to/main-clone/.beads/beads.db - -bd where --json -# {"path": "...", "redirected_from": "...", "prefix": "bd", "database_path": "..."} -``` - -### Limitations - -- **Single-level redirects only**: Redirect chains are not followed (A β†’ B β†’ C won't work) -- **Target must exist**: The redirect target directory must exist and contain a valid database - -### When to Use Redirects - -**Good use cases:** -- Multiple AI agents working on the same project -- Parallel development clones (feature work, bug fixes) -- Testing clones that should see production issues - -**Not recommended for:** -- Separate projects (use separate databases) -- Long-lived forks (they should have their own issues) -- Git worktrees (each should have its own `.beads` directory) - -## Handling Merge Conflicts - -**With hash-based IDs (v0.20.1+), ID collisions are eliminated.** Different issues get different hash IDs, so concurrent creation doesn't cause conflicts. - -### Dolt Native Merge (Default) - -Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects and resolves conflicts automatically where possible: - -```bash -# Pull with automatic merge -bd dolt pull - -# Check for unresolved conflicts -bd vc conflicts - -# Resolve if needed -bd vc resolve -``` - -### Understanding Same-ID Scenarios - -When you encounter the same ID during a Dolt pull or database bootstrap, it's an **update operation**, not a collision: - -- Hash IDs are content-based and remain stable across updates -- Same ID + different fields = normal update to existing issue -- Dolt's cell-level merge resolves updates automatically - -**Bootstrapping from an export:** -```bash -# Export from one database -bd export -o data.jsonl - -# Bootstrap a new database from the export -bd init --from-jsonl -``` - -## Custom Git Hooks - -Git hooks can be used to integrate beads with your git workflow: - -### Using the Installer (Recommended) - -```bash -bd hooks install -``` - -This installs hooks for beads data consistency checks during git operations. - -See [DOLT.md](DOLT.md) for details on how the Dolt backend handles sync natively. - -## Extensible Database - -> **Note:** Custom table extensions via `UnderlyingDB()` are a **SQLite-only** pattern. -> With the Dolt backend, build standalone integration tools using bd's CLI with `--json` -> flags, or use `bd query` for direct SQL access. - -For SQLite-backend users, you can extend bd with your own tables and queries: - -- Add custom metadata to issues -- Build integrations with other tools -- Implement custom workflows -- Create reports and analytics - -See [examples/bd-example-extension-go](../examples/bd-example-extension-go/README.md) for a working extension example. - -## Architecture: Storage, RPC, and MCP - -Understanding the role of each component: - -### Beads (Core) -- **Dolt database** (primary) β€” Version-controlled SQL, the source of truth for all issues, dependencies, labels -- **SQLite database** (legacy) β€” Still supported for simple single-user setups -- **Storage layer** β€” Interface-based CRUD operations, dependency resolution, collision detection -- **Business logic** β€” Ready work calculation, merge operations, import/export -- **CLI commands** β€” Direct database access via `bd` command - -### RPC Layer (Server Mode) -- **Multi-writer access** β€” Connects to a running Dolt server (`bd dolt start`) for concurrent clients -- **Used in multi-agent setups** β€” orchestrator environments where multiple agents write simultaneously -- **Not needed for single-user** β€” embedded mode handles all local operations without a server - -### MCP Server (Optional) -- **Protocol adapter** β€” Translates MCP calls to direct CLI invocations -- **Workspace routing** β€” Finds correct `.beads` directory based on working directory -- **Stateless** β€” Doesn't cache or store any issue data itself -- **Editor integration** β€” Makes bd available to Claude, Cursor, and other MCP clients - -**Key principle**: All heavy lifting (dependency graphs, collision resolution, merge logic) happens in the core bd storage layer. The RPC and MCP layers are thin adapters. - -## Next Steps - -- **[README.md](../README.md)** - Core features and quick start -- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions -- **[FAQ.md](FAQ.md)** - Frequently asked questions -- **[CONFIG.md](CONFIG.md)** - Configuration system guide -- **[examples/bd-example-extension-go](../examples/bd-example-extension-go/README.md)** - Working SQLite extension example diff --git a/docs/AIDER_INTEGRATION.md b/docs/AIDER_INTEGRATION.md deleted file mode 100644 index 1a7a76da6..000000000 --- a/docs/AIDER_INTEGRATION.md +++ /dev/null @@ -1,377 +0,0 @@ -# Aider Integration Guide - -This guide explains how to integrate [Aider](https://aider.chat/) with Beads for AI-assisted coding with issue tracking. - -## Overview - -Aider is an AI pair programming tool that works in your terminal. Unlike autonomous AI agents like Claude Code, **Aider requires explicit user confirmation** to run commands via the `/run` command. - -The beads integration for Aider: -- Creates `.aider.conf.yml` with bd workflow instructions -- Provides `.aider/README.md` with quick reference -- Instructs the AI to **suggest** bd commands (not run them automatically) -- Works with aider's human-in-the-loop design philosophy - -## Installation - -### 1. Install Beads - -```bash -# Install beads CLI -curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash - -# Initialize in your project -cd your-project -bd init --quiet -``` - -### 2. Setup Aider Integration - -```bash -# Install aider integration files -bd setup aider - -# Verify installation -bd setup aider --check -``` - -This creates: -- `.aider.conf.yml` - Instructions for the AI about bd workflow -- `.aider/README.md` - Quick reference guide - -### 3. Install Aider - -```bash -# Install aider via pip -pip install aider-chat - -# Or via pipx (recommended) -pipx install aider-chat -``` - -## Usage Workflow - -### Starting a Session - -1. **Start aider in your project:** - ```bash - cd your-project - aider - ``` - -2. **Ask the AI about available work:** - ``` - You: What issues are ready to work on? - - Aider: Let me check the available work. Run: - /run bd ready - ``` - -3. **Run the suggested command:** - ``` - /run bd ready - ``` - -4. **Choose an issue and ask AI to claim it:** - ``` - You: Let's work on bd-42 - - Aider: Great choice! To claim it, run: - /run bd update bd-42 --claim - ``` - -### During Development - -The AI will suggest appropriate bd commands as you work: - -- **Create issues for bugs you find:** - ``` - You: I found a bug in the auth code - - Aider: Let's track that. Run: - /run bd create "Fix auth bug in login handler" --description="Login fails with 500 when password contains quotes" -t bug -p 1 - ``` - -- **Link discovered work:** - ``` - Aider: Since we found this while working on bd-42, run: - /run bd create "Fix auth bug" --description="..." -p 1 --deps discovered-from:bd-42 - ``` - -- **Check issue details:** - ``` - /run bd show bd-42 - ``` - -### Completing Work - -When you're done: - -``` -You: This issue is complete - -Aider: Great! Mark it complete by running: -/run bd close bd-42 --reason "Implemented login fix and added tests" - -Then sync to git: -/run bd dolt push -``` - -## Configuration - -### .aider.conf.yml - -The config file contains instructions for the AI: - -```yaml -# Core workflow rules: -# 1. Track ALL work in bd (never use markdown TODOs) -# 2. Suggest 'bd ready' to find available work -# 3. Suggest 'bd create' for new issues/tasks/bugs -# 4. Suggest 'bd dolt push' at end of session -# 5. ALWAYS suggest commands - user will run them via /run -``` - -You can customize this file to add project-specific instructions. - -### Aider Commands vs bd Commands - -**Aider commands** start with `/` and control aider itself: -- `/run ` - Run a shell command -- `/add ` - Add file to context -- `/help` - Show aider help - -**bd commands** are run via `/run`: -- `/run bd ready` - Check available work -- `/run bd create "..."` - Create an issue -- `/run bd show bd-42` - View issue details - -## Common Patterns - -### Starting Work - -```bash -# Check what's available -/run bd ready - -# Claim an issue -/run bd update bd-abc --claim -``` - -### Discovering Work - -```bash -# Create a new issue -/run bd create "Refactor auth module" --description="Current auth code has tight coupling" -t task -p 2 - -# Link it to current work -/run bd dep add bd-new --type discovered-from --target bd-abc -``` - -### Completing Work - -```bash -# Close the issue -/run bd close bd-abc --reason "Implemented and tested" - -# Sync to git -/run bd dolt push -``` - -### Checking Status - -```bash -# View issue details -/run bd show bd-abc - -# List all open issues -/run bd list --status=open - -# Check dependencies -/run bd dep tree bd-abc -``` - -## Comparison: Aider vs Claude Code - -### Aider (Human-in-the-Loop) - -- βœ… User must confirm all commands via `/run` -- βœ… Full control over what gets executed -- βœ… AI **suggests** bd commands -- ⚠️ More manual interaction required - -### Claude Code (Autonomous) - -- βœ… AI directly executes bd commands -- βœ… Faster workflow (no confirmation needed) -- βœ… Hooks auto-inject bd context -- ⚠️ Less user control over command execution - -**Both approaches work well with beads!** Choose based on your preference for automation vs. control. - -## Tips for Aider Users - -### 1. Ask for Suggestions - -Instead of running commands yourself, ask the AI: -``` -You: How do I check what work is available? -Aider: Run `/run bd ready` to see all unblocked issues -``` - -### 2. Let the AI Track Work - -The AI knows the bd workflow and will suggest appropriate commands: -``` -You: I'm starting work on the login feature -Aider: First, let's claim it. Run: -/run bd update bd-xyz --claim -``` - -### 3. Use bd prime for Context - -Get the full workflow guide: -```bash -/run bd prime -``` - -The AI will read this and have complete context about bd commands. - -### 4. Create Aliases - -Add to your shell config for faster commands: -```bash -alias bdr='/run bd ready' -alias bdc='/run bd create' -alias bds='/run bd dolt push' -``` - -Then in aider: -``` -bdr # Instead of /run bd ready -bdc "Fix bug" -t bug # Instead of /run bd create "Fix bug" -t bug -``` - -## Troubleshooting - -### "The AI isn't suggesting bd commands" - -1. Check that `.aider.conf.yml` exists: - ```bash - bd setup aider --check - ``` - -2. Reload aider to pick up the config: - ```bash - # Exit aider (Ctrl-D or /exit) - # Restart aider - aider - ``` - -3. Explicitly ask about bd: - ``` - You: What should I use for issue tracking? - Aider: This project uses Beads (bd) for issue tracking... - ``` - -### "Commands are failing" - -Make sure you're in a beads-initialized directory: -```bash -/run bd doctor -``` - -If not initialized: -```bash -/run bd init --quiet -``` - -### "I want to remove the integration" - -```bash -bd setup aider --remove -``` - -This removes `.aider.conf.yml` and `.aider/README.md`. - -## Advanced Usage - -### Multi-File Context - -Aider can track multiple files. Combine with bd: - -``` -You: Add the auth files to context and check for related issues - -/run bd list --json | grep -i auth -/add src/auth/*.py -``` - -### Batch Operations - -Run multiple bd commands in sequence: -```bash -# In your shell (not aider) -bd ready && bd show bd-42 && bd update bd-42 --claim -``` - -### Integration with Git - -Aider handles git commits. bd tracks issues. They work together: - -1. Claim issue: `/run bd update bd-42 --claim` -2. Make changes with aider -3. Aider commits changes -4. Complete issue: `/run bd close bd-42` -5. Sync issues: `/run bd dolt push` - -## Example Session - -``` -$ aider - -You: What issues are ready to work on? - -Aider: Let me check. Run: -/run bd ready - -πŸ“‹ Ready work (3 issues with no blockers): -1. [P1] bd-42: Fix login bug -2. [P2] bd-99: Add password reset -3. [P3] bd-17: Refactor auth tests - -You: Let's work on bd-42 - -Aider: Great! First claim it: -/run bd update bd-42 --claim - -You: Can you show me the details? - -Aider: Run: -/run bd show bd-42 - -[Shows issue details] - -You: Ok, add the auth files to context - -Aider: Added src/auth/login.py and src/auth/utils.py - -You: Fix the bug described in the issue - -[Aider makes the changes] - -You: Looks good! Mark it complete - -Aider: Run: -/run bd close bd-42 --reason "Fixed login bug - added input validation" - -Then sync: -/run bd dolt push -``` - -## References - -- [Aider Documentation](https://aider.chat/docs/) -- [Beads Documentation](https://github.com/gastownhall/beads) -- [AGENTS.md](../AGENTS.md) - Complete bd workflow guide -- [QUICKSTART.md](QUICKSTART.md) - Quick start guide diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 14c6c89c0..000000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,368 +0,0 @@ -# Architecture - -This document describes bd's overall architecture - the data model, sync mechanism, and how components fit together. For product scope boundaries, see [PROJECT_CHARTER.md](../engdocs/PROJECT_CHARTER.md). For internal implementation details (FlushManager, Blocked Cache), see [INTERNALS.md](../engdocs/INTERNALS.md). - -## The Two-Layer Data Model - -bd's core design enables a distributed, Dolt-powered issue tracker that feels like a centralized database. The architecture has two synchronized layers: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ CLI Layer β”‚ -β”‚ β”‚ -β”‚ bd create, list, update, close, ready, show, dep, sync, ... β”‚ -β”‚ - Cobra commands in cmd/bd/ β”‚ -β”‚ - All commands support --json for programmatic use β”‚ -β”‚ - Direct DB access (server mode via dolt sql-server) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - v -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Dolt Database β”‚ -β”‚ (.beads/dolt/) β”‚ -β”‚ β”‚ -β”‚ - Version-controlled SQL database with cell-level merge β”‚ -β”‚ - Server mode via dolt sql-server (multi-writer capable) β”‚ -β”‚ - Fast queries, indexes, foreign keys β”‚ -β”‚ - Issues, dependencies, labels, comments, events β”‚ -β”‚ - Automatic Dolt commits on every write β”‚ -β”‚ - Native push/pull to Dolt remotes β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - Dolt push/pull - (or federation peer sync) - β”‚ - v -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Remote (Dolt or Git) β”‚ -β”‚ β”‚ -β”‚ - Dolt remotes (DoltHub, S3, GCS, filesystem) β”‚ -β”‚ - All collaborators share the same issue database β”‚ -β”‚ - Cell-level merge for conflict resolution β”‚ -β”‚ - Protected branch support via separate sync branch β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Why This Design? - -**Dolt for versioned SQL:** Queries complete in milliseconds with full SQL support. Dolt adds native version control β€” every write is automatically committed to Dolt history, providing a complete audit trail. Cell-level merge resolves conflicts automatically. - -**Dolt for distribution:** Native push/pull to Dolt remotes (DoltHub, S3, GCS). No special sync server needed. Issues travel with your code. Offline work just works. - -**Export and backup:** `bd export` outputs issue JSONL for data migration and interoperability. Use `bd backup init` / `bd backup sync` to push Dolt-native backups (preserving full commit history) to a filesystem path or DoltHub, and `bd backup restore` to restore from them. - -## Write Path - -When you create or modify an issue: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ CLI Command │───▢│ Dolt Write │───▢│ Dolt Commit β”‚ -β”‚ (bd create) β”‚ β”‚ (immediate) β”‚ β”‚ (automatic) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -1. **Command executes:** `bd create "New feature"` writes to Dolt immediately -2. **Dolt commit:** Every write is automatically committed to Dolt history -3. **Sync:** Use `bd dolt push` to share changes with Dolt remotes - -Key implementation: -- Dolt storage: `internal/storage/dolt/` -- Export (for portability): `cmd/bd/export.go` - -## Read Path - -All queries run directly against the local Dolt database: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ CLI Query │───▢│ Dolt Query β”‚ -β”‚ (bd ready) β”‚ β”‚ (SQL) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -1. **Query:** Commands read from fast local Dolt database via SQL -2. **Sync:** Use `bd dolt pull` to fetch updates from Dolt remotes - -Key implementation: -- Backup restore: `cmd/bd/backup_restore.go` -- Issue bootstrap/migration: `cmd/bd/init.go` -- Dolt storage: `internal/storage/dolt/` - -## Hash-Based Collision Prevention - -The key insight that enables distributed operation: **content-based hashing for deduplication**. - -### The Problem - -Sequential IDs (bd-1, bd-2, bd-3) cause collisions when multiple agents create issues concurrently: - -``` -Branch A: bd create "Add OAuth" β†’ bd-10 -Branch B: bd create "Add Stripe" β†’ bd-10 (collision!) -``` - -### The Solution - -Hash-based IDs derived from random UUIDs ensure uniqueness: - -``` -Branch A: bd create "Add OAuth" β†’ bd-a1b2 -Branch B: bd create "Add Stripe" β†’ bd-f14c (no collision) -``` - -### How It Works - -1. **Issue creation:** Generate random UUID, derive short hash as ID -2. **Progressive scaling:** IDs start at 4 chars, grow to 5-6 chars as database grows -3. **Content hashing:** Each issue has a content hash for change detection -4. **Merge logic:** Same ID + different content = update, same ID + same content = skip - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Merge Logic β”‚ -β”‚ (used by Dolt pull and init --from-jsonl) β”‚ -β”‚ β”‚ -β”‚ For each issue in incoming data: β”‚ -β”‚ 1. Compute content hash β”‚ -β”‚ 2. Look up existing issue by ID β”‚ -β”‚ 3. Compare hashes: β”‚ -β”‚ - Same hash β†’ skip (already present) β”‚ -β”‚ - Different hash β†’ update (newer version) β”‚ -β”‚ - No match β†’ create (new issue) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -This eliminates the need for central coordination while ensuring all machines converge to the same state. - -See [COLLISION_MATH.md](../engdocs/COLLISION_MATH.md) for birthday paradox calculations on hash length vs collision probability. - -## Server Architecture - -Each workspace can run its own Dolt server for multi-writer access: - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Dolt Server Mode β”‚ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ RPC Server β”‚ β”‚ dolt β”‚ β”‚ -β”‚ β”‚ β”‚ β”‚ sql-server β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ β”‚ β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ β”‚ β”‚ -β”‚ v β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Dolt β”‚ β”‚ -β”‚ β”‚ Database β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - - CLI commands ───SQL───▢ dolt sql-server ───▢ Database - or - CLI commands ───SQL───▢ Database (embedded mode) -``` - -**Server mode:** -- Connects to `dolt sql-server` (multi-writer, high-concurrency) -- PID file at `.beads/dolt-server.pid` -- Logs at `.beads/dolt-server.log` -- **Shared server mode** (opt-in): all projects share a single Dolt server at - `~/.beads/shared-server/` instead of per-project servers. Enable via - `dolt.shared-server: true` in config.yaml or `BEADS_DOLT_SHARED_SERVER=1`. - -**Embedded mode:** -- Direct database access (single-writer, no server process) - -**Communication:** -- Protocol defined in `internal/rpc/protocol.go` -- Used by Dolt server mode for multi-writer access - -## Data Types - -Core types in `internal/types/types.go`: - -| Type | Description | Key Fields | -|------|-------------|------------| -| **Issue** | Work item | ID, Title, Description, Status, Priority, Type | -| **Dependency** | Relationship | FromID, ToID, Type (blocks/related/parent-child/discovered-from) | -| **Label** | Tag | Name, Color, Description | -| **Comment** | Discussion | IssueID, Author, Content, Timestamp | -| **Event** | Audit trail | IssueID, Type, Data, Timestamp | - -### Dependency Types - -| Type | Semantic | Affects `bd ready`? | -|------|----------|---------------------| -| `blocks` | Issue X must close before Y starts | Yes | -| `parent-child` | Hierarchical (epic/subtask) | Yes (children blocked if parent blocked) | -| `related` | Soft link for reference | No | -| `discovered-from` | Found during work on parent | No | - -### Status Flow - -``` -open ──▢ in_progress ──▢ closed - β”‚ β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - (reopen) -``` - -### Issue Schema - -Each issue in the Dolt database (and in JSONL exports via `bd export`) has the following fields. Fields marked with `(optional)` use `omitempty` and are excluded when empty/zero. - -The schema is stable by default. Prefer issue metadata for integration, -orchestration, or team-specific data before adding new first-class fields; see -[Project Charter: Schema Boundary](../engdocs/PROJECT_CHARTER.md#schema-boundary). - -**Core Identification:** - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Unique identifier (e.g., `bd-a1b2`) | - -**Issue Content:** - -| Field | Type | Description | -|-------|------|-------------| -| `title` | string | Issue title (required) | -| `description` | string | Detailed description (optional) | -| `design` | string | Design notes (optional) | -| `acceptance_criteria` | string | Acceptance criteria (optional) | -| `notes` | string | Additional notes (optional) | - -**Status & Workflow:** - -| Field | Type | Description | -|-------|------|-------------| -| `status` | string | Current status: `open`, `in_progress`, `blocked`, `deferred`, `closed`, `tombstone`, `pinned`, `hooked` (optional, defaults to `open`) | -| `priority` | int | Priority 0-4 where 0=critical, 4=backlog | -| `issue_type` | string | Type: `bug`, `feature`, `task`, `epic`, `chore`, `message`, `merge-request`, `molecule`, `gate`, `agent`, `role`, `convoy` (optional, defaults to `task`) | - -**Assignment:** - -| Field | Type | Description | -|-------|------|-------------| -| `assignee` | string | Assigned user/agent (optional) | -| `estimated_minutes` | int | Time estimate in minutes (optional) | - -**Timestamps:** - -| Field | Type | Description | -|-------|------|-------------| -| `created_at` | RFC3339 | When issue was created | -| `created_by` | string | Who created the issue (optional) | -| `updated_at` | RFC3339 | Last modification time | -| `closed_at` | RFC3339 | When issue was closed (optional, set when status=closed) | -| `close_reason` | string | Reason provided when closing (optional) | - -**External Integration:** - -| Field | Type | Description | -|-------|------|-------------| -| `external_ref` | string | External reference (e.g., `gh-9`, `jira-ABC`) (optional) | - -**Relational Data:** - -| Field | Type | Description | -|-------|------|-------------| -| `labels` | []string | Tags attached to the issue (optional) | -| `dependencies` | []Dependency | Relationships to other issues (optional) | -| `comments` | []Comment | Discussion comments (optional) | - -**Tombstone Fields (soft-delete):** - -| Field | Type | Description | -|-------|------|-------------| -| `deleted_at` | RFC3339 | When deleted (optional, set when status=tombstone) | -| `deleted_by` | string | Who deleted (optional) | -| `delete_reason` | string | Why deleted (optional) | -| `original_type` | string | Issue type before deletion (optional) | - -**Note:** Fields with `json:"-"` tags (like `content_hash`, `source_repo`, `id_prefix`) are internal and not included in exports. - -## Directory Structure - -``` -.beads/ -β”œβ”€β”€ dolt/ # Dolt database, sql-server.pid, sql-server.log (gitignored) -β”œβ”€β”€ metadata.json # Backend config (local, gitignored) -└── config.yaml # Project config (optional) -``` - -## Key Code Paths - -| Area | Files | -|------|-------| -| CLI entry | `cmd/bd/main.go` | -| Storage interface | `internal/storage/storage.go` | -| Dolt implementation | `internal/storage/dolt/` | -| RPC protocol | `internal/rpc/protocol.go`, `server_*.go` | -| Export logic (portability) | `cmd/bd/export.go` | -| Backup restore | `cmd/bd/backup_restore.go` | -| Issue bootstrap/migration | `cmd/bd/init.go` | - -## Wisps and Molecules - -**Molecules** are template work items that define structured workflows. When spawned, they create **wisps** - ephemeral child issues that track execution steps. - -> **For full documentation** on the molecular chemistry metaphor (protos, pour, bond, squash, burn), see [MOLECULES.md](MOLECULES.md). - -### Wisp Lifecycle - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ bd mol wisp │───▢│ Wisp Issues │───▢│ bd mol squash β”‚ -β”‚ (from template) β”‚ β”‚ (local-only) β”‚ β”‚ (β†’ digest) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -1. **Create:** Create wisps from a molecule template -2. **Execute:** Agent works through wisp steps (local database only) -3. **Squash:** Compress wisps into a permanent digest issue - -### Why Wisps Don't Sync - -Wisps are intentionally **local-only**: - -- They exist only in the spawning agent's local database -- They are **never exported or synced** -- They cannot resurrect from other clones (they were never there) -- They are **hard-deleted** when squashed (no tombstones needed) - -This design enables: - -- **Fast local iteration:** No sync overhead during execution -- **Clean history:** Only the digest (outcome) enters git -- **Agent isolation:** Each agent's execution trace is private -- **Bounded storage:** Wisps don't accumulate across clones - -### Wisp vs Regular Issue Deletion - -| Aspect | Regular Issues | Wisps | -|--------|---------------|-------| -| Synced to remotes | Yes | No | -| Tombstone on delete | Yes | No | -| Can resurrect | Yes (without tombstone) | No (never synced) | -| Deletion method | `CreateTombstone()` | `DeleteIssue()` (hard delete) | - -The `bd mol squash` command uses hard delete intentionally - tombstones would be wasted overhead for data that never leaves the local database. - -### Future Directions - -- **Separate wisp repo:** Keep wisps in a dedicated ephemeral git repo -- **Digest migration:** Explicit step to promote digests to main repo -- **Wisp retention:** Option to preserve wisps in local git history - -## Related Documentation - -- [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md) - How cross-machine sync works (Dolt source of truth, wire format, anti-patterns) -- [PROJECT_CHARTER.md](../engdocs/PROJECT_CHARTER.md) - Product scope and boundaries -- [MOLECULES.md](MOLECULES.md) - Molecular chemistry metaphor (protos, pour, bond, squash, burn) -- [INTERNALS.md](../engdocs/INTERNALS.md) - FlushManager, Blocked Cache implementation details -- [ADVANCED.md](ADVANCED.md) - Advanced features and configuration -- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Recovery procedures and common issues -- [FAQ.md](FAQ.md) - Common questions about the architecture -- [COLLISION_MATH.md](../engdocs/COLLISION_MATH.md) - Hash collision probability analysis diff --git a/docs/CLAUDE_INTEGRATION.md b/docs/CLAUDE_INTEGRATION.md deleted file mode 100644 index 53fbb678c..000000000 --- a/docs/CLAUDE_INTEGRATION.md +++ /dev/null @@ -1,117 +0,0 @@ -# Claude Code Integration Design - -This document explains design decisions for Claude Code integration in beads. - -## Integration Approach - -**Recommended: CLI + Hooks** - Beads uses a simple, universal approach to Claude Code integration: -- `bd prime` command for context injection (~1-2k tokens) -- Hooks (SessionStart) for automatic context refresh -- Direct CLI commands with `--json` flags -- Optional: Plugin for slash commands and enhanced UX - -**Alternative: MCP Server** - For MCP-only environments (Claude Desktop, no shell): -- Higher context overhead (MCP tool schemas) -- Use only when CLI is unavailable - -## Why CLI + Hooks Over MCP? - -**Context efficiency matters**, even with large context windows: - -1. **Compute cost scales with tokens** - Every token in your context consumes compute on every inference, regardless of whether it's used -2. **Latency increases with context** - Larger prompts take longer to process -3. **Energy consumption** - Each token has environmental impact; lean prompts are more sustainable -4. **Attention quality** - Models attend better to smaller, focused contexts - -**The math:** -- MCP tool schemas can add 10-50k tokens to context (depending on number of tools) -- `bd prime` adds ~1-2k tokens of workflow context -- That's 10-50x less context overhead - -**When context size doesn't matter:** -- MCP-only environments where CLI isn't available (Claude Desktop) -- Very short conversations where context overhead is negligible - -**When to prefer CLI + hooks:** -- Any environment with shell access (Claude Code, Cursor, Windsurf, etc.) -- Long conversations or coding sessions -- Multi-editor workflows (CLI is universal) - -## Why Not Claude Skills? - -**Decision: Beads does NOT use or require Claude Skills (.claude/skills/)** - -### Reasons - -1. **Redundant with bd prime** - - `bd prime` already provides workflow context (~1-2k tokens) - - Skills would duplicate this information - - More systems = more complexity - -2. **Simplicity is core to beads** - - Workflow fits in simple command set: ready β†’ create β†’ update β†’ close β†’ sync - - Already well-documented in ~1-2k tokens - - Complex workflow orchestration not needed - -3. **Editor agnostic** - - Skills are Claude-specific - - Breaks beads' editor-agnostic philosophy - - Cursor, Windsurf, Zed, etc. wouldn't benefit - -4. **Maintenance burden** - - Another system to document and test - - Another thing that can drift out of sync - - Another migration path when things change - -### If Skills were needed... - -They should be: -- Provided by the beads plugin (not bd core tool) -- Complementary (not replacing) bd prime -- Optional power-user workflows only -- Opt-in, never required - -### Current approach is better - -- βœ… `bd prime` - Universal context injection -- βœ… Hooks - Automatic context refresh -- βœ… Plugin - Optional Claude-specific enhancements -- βœ… MCP - Optional native tool access (legacy) -- ❌ Skills - Unnecessary complexity - -Users who want custom Skills can create their own, but beads doesn't ship with or require them. - -## Installation - -```bash -# Install Claude Code hooks globally -bd setup claude - -# Install for this project only -bd setup claude --project - -# Use stealth mode (flush only, no git operations) -bd setup claude --stealth - -# Check installation status -bd setup claude --check - -# Remove hooks -bd setup claude --remove -``` - -**What it installs:** -- SessionStart hook: Runs `bd prime` when Claude Code starts a session -- SessionStart hook: Runs `bd prime` when Claude Code starts a session and after compaction - -## Related Files - -- `cmd/bd/prime.go` - Context generation -- `cmd/bd/setup/claude.go` - Hook installation -- `cmd/bd/doctor/claude.go` - Integration verification -- `engdocs/CLAUDE.md` - General project guidance for Claude - -## References - -- [Claude Skills Documentation](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills) -- [Claude Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) diff --git a/docs/CODEX_INTEGRATION.md b/docs/CODEX_INTEGRATION.md deleted file mode 100644 index 9ad180e83..000000000 --- a/docs/CODEX_INTEGRATION.md +++ /dev/null @@ -1,74 +0,0 @@ -# Codex Integration - -Beads supports Codex through the shared `beads` skill, `AGENTS.md` guidance, and native Codex lifecycle hooks. - -## Quick Setup - -```bash -bd setup codex -``` - -`bd init` also runs this project setup by default unless `--skip-agents` or `--stealth` is used. Project setup writes: - -- `.agents/skills/beads/` for the Beads skill. -- `AGENTS.md` with a managed Beads section. -- `.codex/config.toml` with `[features].hooks = true`. -- `.codex/hooks.json` with the Beads hook fallback. - -Global setup uses `bd setup codex --global` and writes under `$CODEX_HOME` when set, otherwise `~/.codex`. - -## Plugin-Managed Hooks - -The bundled Codex plugin keeps its hook config at `plugins/beads/.codex-plugin/hooks/hooks.json`; `plugins/beads/.codex-plugin/plugin.json` declares it as `"hooks": "./hooks/hooks.json"`. On Codex 0.129.0+, use `/hooks` to inspect or toggle these handlers. - -The plugin and `bd setup codex` fallback install the same lifecycle: - -- `SessionStart` with matcher `startup|resume|clear`: injects full `bd prime` output as developer context. -- `PreCompact` with matcher `manual|auto`: checks `bd prime --memories-only` and surfaces a warning if Beads context is unavailable. -- `PostCompact` with matcher `manual|auto`: records that the Codex session needs a Beads refresh. -- `UserPromptSubmit`: if a refresh marker exists, injects full `bd prime` output once and clears the marker. - -`PreCompact` cannot preserve Beads context by printing text; compact hook plain stdout is ignored by Codex. Beads therefore uses `PostCompact` plus the next `UserPromptSubmit` to recover context after successful manual or automatic compaction. - -Refresh markers are stored in a user cache/temp directory keyed by Codex `session_id` and workspace path. They are not written to tracked files or to the Beads database. - -## Manual Fallback - -If you do not use the plugin, `bd setup codex` manages `.codex/hooks.json` directly. The equivalent manual shape is: - -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup|resume|clear", - "hooks": [{ "type": "command", "command": "bd codex-hook SessionStart" }] - } - ], - "PreCompact": [ - { - "matcher": "manual|auto", - "hooks": [{ "type": "command", "command": "bd codex-hook PreCompact" }] - } - ], - "PostCompact": [ - { - "matcher": "manual|auto", - "hooks": [{ "type": "command", "command": "bd codex-hook PostCompact" }] - } - ], - "UserPromptSubmit": [ - { - "hooks": [{ "type": "command", "command": "bd codex-hook UserPromptSubmit" }] - } - ] - } -} -``` - -Ensure `config.toml` enables: - -```toml -[features] -hooks = true -``` diff --git a/docs/CONFIG.md b/docs/CONFIG.md deleted file mode 100644 index fe7cea86f..000000000 --- a/docs/CONFIG.md +++ /dev/null @@ -1,1033 +0,0 @@ -# Configuration System - -Last reviewed: 2026-05-08 - -Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and -`internal/configfile/`. - -bd has two complementary configuration systems: - -1. **Tool-level configuration** (Viper): startup settings, flags, output format, and other CLI behaviour -2. **Project-level configuration** (`bd config`): integration data and project-specific settings; startup-sensitive keys are routed to `config.yaml` - -## Tool-Level Configuration (Viper) - -### Overview - -Tool preferences control how `bd` behaves globally or per-user. These are stored in config files or environment variables and managed by [Viper](https://github.com/spf13/viper). - -**Configuration precedence** (highest to lowest): -1. Command-line flags (`--json`, `--dolt-auto-commit`, etc.) -2. Environment variables (`BD_JSON`, `BD_DOLT_AUTO_COMMIT`, etc.) -3. Merged config files (`~/.beads/config.yaml`, `~/.config/bd/config.yaml`, `.beads/config.yaml`, and `BEADS_DIR/config.yaml`) -4. Defaults - -### Config File Locations - -Config files are merged from lowest to highest priority: - -1. `~/.beads/config.yaml` - legacy user settings -2. `~/.config/bd/config.yaml` - user settings; this path is checked explicitly even on platforms whose native user-config directory differs -3. `.beads/config.yaml` - project-specific tool settings, discovered by walking up from the current directory -4. `BEADS_DIR/config.yaml` - highest-priority runtime workspace override when `BEADS_DIR` points at a different `.beads` directory - -When a project config exists, `.beads/config.local.yaml` is merged last for -machine-specific overrides that should not be committed. - -### Supported Settings - -Common tool-level settings you can configure: - -| Setting | Flag | Environment Variable | Default | Description | -|---------|------|---------------------|---------|-------------| -| `json` | `--json` | `BD_JSON` | `false` | Output in JSON format | -| `no-push` | `--no-push` | `BD_NO_PUSH` | `false` | Skip pushing to remote in `bd dolt push` | -| `agent.profile` | - | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority wording: `conservative`, `minimal`, `team-maintainer` (see [SETUP.md](SETUP.md#policy-profiles)); invalid values fall back to `conservative` | -| `federation.remote` | - | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL for federation | -| `federation.sovereignty` | - | `BD_FEDERATION_SOVEREIGNTY` | (none) | Data sovereignty tier: `T1`, `T2`, `T3`, `T4` | -| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | (Dolt backend) Automatically create a Dolt commit after successful write commands | -| `create.require-description` | - | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description when creating issues | -| `validation.on-create` | - | `BD_VALIDATION_ON_CREATE` | `none` | Template validation on create: `none`, `warn`, `error` | -| `validation.on-sync` | - | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync: `none`, `warn`, `error` | -| `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by bd prime (0 = unlimited) | -| `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by bd prime, whole-memory boundaries (0 = unlimited) | -| `git.author` | - | `BD_GIT_AUTHOR` | (none) | Override commit author for beads commits | -| `git.no-gpg-sign` | - | `BD_GIT_NO_GPG_SIGN` | `false` | Disable GPG signing for beads commits | -| `list.limit` | `--limit` / `-n` | `BD_LIST_LIMIT` | `50` | Default limit for `bd list` results | -| `directory.labels` | - | - | (none) | Map directories to labels for automatic filtering | -| `external_projects` | - | - | (none) | Map project names to paths for cross-project deps | -| `backup.enabled` | - | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` | -| `backup.interval` | - | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups | -| `dolt.auto-push` | - | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (explicit opt-in) | -| `dolt.auto-push-interval` | - | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes | -| `dolt.auto-push-timeout` | - | `BD_DOLT_AUTO_PUSH_TIMEOUT` | `30s` | Timeout for a single auto-push attempt | -| pre-push fsck timeout | - | `BEADS_FSCK_TIMEOUT` | `30s` | Runtime-only timeout for the pre-push `dolt fsck --quiet` integrity check | -| `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share a single Dolt server across all projects at `~/.beads/shared-server/` | -| `db` | `--db` | `BD_DB` | (auto-discover) | Database path | -| `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail (see below) | - -**Backend note:** Dolt is the only storage backend. By default, Dolt runs in embedded mode (in-process, no server). Use `bd init --server` or `BEADS_DOLT_SERVER_MODE=1` for server mode. See [DOLT.md](DOLT.md) for details. - -### Dolt Auto-Commit (SQL commit vs Dolt commit) - -When using the **Dolt backend**, there are two different kinds of β€œcommit”: - -- **SQL transaction commit**: what happens when a `bd` command updates tables successfully (durable in the Dolt *working set*). -- **Dolt version-control commit**: what records those changes into Dolt’s *history* (visible in `bd vc log`, push/pull/merge workflows). - -By default, `bd` is configured to **auto-commit Dolt history after each successful write command**: - -- **Default**: `dolt.auto-commit: on` -- **Disable for a single command**: - -```bash -bd --dolt-auto-commit off create "No commit for this one" -``` - -- **Disable in config** (`.beads/config.yaml` or `~/.config/bd/config.yaml`): - -```yaml -dolt: - auto-commit: off -``` - -**Caveat:** enabling this creates **more Dolt commits** over time (one per write command). This is intentional so changes are not left only in the working set. - -### Auto-Backup - -Periodic Dolt-native backup to `.beads/backup/` provides an off-machine recovery path. Local Dolt snapshots (via `dolt.auto-commit`) remain the primary safety net; backup is a secondary layer. - -This is a full database backup, unlike `bd export` or `.beads/issues.jsonl`. -It preserves Dolt state such as tables, branches, commit history, and -working-set data. - -```yaml -backup: - enabled: true # Enable auto-backup after write commands - interval: 15m # Minimum time between auto-backups -``` - -**How it works:** -- After each write command (in PersistentPostRun), `bd` checks the Dolt HEAD commit hash against the last backup state -- If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` -- Full database state and commit history are preserved in the backup -- State is tracked in `.beads/backup/backup_state.json` - -**Manual commands:** -- `bd backup init ` β€” register a backup destination (filesystem or DoltHub URL) -- `bd backup sync` β€” push to the configured backup destination -- `bd backup restore [path]` β€” restore from a backup (`--force` to overwrite) -- `bd backup remove` β€” unregister the backup destination -- `bd backup status` β€” show backup configuration and last sync time - -### Dolt Auto-Push - -By default, `bd` does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race. - -```yaml -dolt: - auto-push: false # Explicit opt-in only; set true for single-writer setups - auto-push-interval: 5m # Minimum time between auto-pushes - auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable -``` - -**How it works:** -- After each write command (in PersistentPostRun, after auto-commit and auto-backup), `bd` checks whether a push is due -- Pushes are debounced: skipped if the last push was less than `dolt.auto-push-interval` ago -- Change detection: skipped if the Dolt HEAD commit hasn't changed since last push -- Push failures are warnings only (non-fatal) -- Last push time and commit are tracked in the metadata table - -**Opt in:** -```yaml -dolt: - auto-push: true -``` - -### Actor Identity Resolution - -The actor name (used for `created_by` in issues and audit trails) is resolved in this order: - -1. `--actor` flag (explicit override) -2. `BEADS_ACTOR` environment variable -3. `BD_ACTOR` environment variable (deprecated alias, kept for backwards compatibility) -4. `git config user.name` -5. `$USER` environment variable (system username fallback) -6. `"unknown"` (final fallback) - -For most developers, no configuration is needed - beads will use your git identity automatically. This ensures your issue authorship matches your commit authorship. - -To override, set `BEADS_ACTOR` in your shell profile: -```bash -export BEADS_ACTOR="my-github-handle" -``` - -### Sync Mode Configuration - -The sync mode controls how beads synchronizes data with git and/or Dolt remotes. - -#### Sync Mode - -Beads uses `dolt-native` sync mode exclusively. Dolt remotes handle sync directly with cell-level merge. Use `bd export` for issue portability, and `bd backup init` / `bd backup sync` / `bd backup restore` for Dolt-native backups. - -#### Federation Configuration - -- `federation.remote`: Dolt remote URL (e.g., `dolthub://org/beads`, `gs://bucket/beads`, `s3://bucket/beads`, `az://account.blob.core.windows.net/container/beads`) -- `federation.sovereignty`: Data sovereignty tier: - - `T1`: Full sovereignty - data never leaves controlled infrastructure - - `T2`: Regional sovereignty - data stays within region/jurisdiction - - `T3`: Provider sovereignty - data with trusted cloud provider - - `T4`: No restrictions - data can be anywhere - -#### Example Configuration - -```yaml -# .beads/config.yaml -# Optional: Dolt federation -federation: - remote: dolthub://myorg/beads - sovereignty: T2 -``` - -### Example Config File - -`~/.config/bd/config.yaml`: -```yaml -# Default to JSON output for scripting -json: true - -# Dolt auto-commit (creates Dolt history commit after each write) -dolt: - auto-commit: on -``` - -`.beads/config.yaml` (project-specific): -```yaml -# Require descriptions on all issues (enforces context for future work) -create: - require-description: true - -# Template validation settings (bd-t7jq) -# Validates that issues include required sections based on issue type -# Values: none (default), warn (print warning), error (block operation) -validation: - on-create: warn # Warn when creating issues missing sections - on-sync: none # No validation on sync (backwards compatible) - -# Git commit signing options (GH#600) -# Useful when you have Touch ID commit signing that prompts for each commit -git: - author: "beads-bot " # Override commit author - no-gpg-sign: true # Disable GPG signing - -# Directory-aware label scoping for monorepos (GH#541) -# When running bd ready/list from a matching directory, issues with -# that label are automatically shown (as if --label-any was passed) -directory: - labels: - packages/maverick: maverick - packages/agency: agency - packages/io: io - -# Feedback title formatting for mutating commands (GH#1384) -# 0 = hide titles, N > 0 = truncate to N characters -output: - title-length: 255 - -# Cross-project dependency resolution (bd-h807) -# Maps project names to paths for resolving external: blocked_by references -# Paths can be relative (from cwd) or absolute -external_projects: - beads: ../beads - other-project: /path/to/other-project -``` - -### Why Two Systems? - -**Tool settings (Viper)** are user preferences: -- How should I see output? (`--json`) -- Should Dolt auto-commit? (`--dolt-auto-commit`) -- How should the CLI behave? - -**Project config (`bd config`)** is project data: -- What's our Jira URL? -- What are our Linear tokens? -- How do we map statuses? - -This separation is correct: **tool settings are user-specific, project config is team-shared**. - -Agents benefit from `bd config`'s structured CLI interface over manual YAML editing. - -## Project-Level Configuration (`bd config`) - -### Overview - -Project configuration is: -- **Per-project**: Isolated to each `.beads/` database -- **Version-control-friendly**: Stored in the database, queryable and scriptable -- **Machine-readable**: JSON output for automation -- **Namespace-based**: Organized by integration or purpose - -## Commands - -### Set Configuration - -```bash -bd config set -bd config set --json # JSON output -``` - -Examples: -```bash -bd config set jira.url "https://company.atlassian.net" -bd config set jira.project "PROJ" -bd config set jira.status_map.todo "open" -``` - -### Get Configuration - -```bash -bd config get -bd config get --json # JSON output -``` - -Examples: -```bash -bd config get jira.url -# Output: https://company.atlassian.net - -bd config get --json jira.url -# Output: {"key":"jira.url","value":"https://company.atlassian.net"} -``` - -### List All Configuration - -```bash -bd config list -bd config list --json # JSON output -``` - -Example output: -``` -Configuration: - compact_tier1_days = 90 - compact_tier1_dep_levels = 2 - jira.project = PROJ - jira.url = https://company.atlassian.net -``` - -JSON output: -```json -{ - "compact_tier1_days": "90", - "compact_tier1_dep_levels": "2", - "jira.project": "PROJ", - "jira.url": "https://company.atlassian.net" -} -``` - -### Unset Configuration - -```bash -bd config unset -bd config unset --json # JSON output -``` - -Example: -```bash -bd config unset jira.url -``` - -## Namespace Convention - -Configuration keys use dot-notation namespaces to organize settings: - -### Core Namespaces - -- `compact_*` - Compaction settings (used by `bd admin compact`) -- `issue_prefix` - Issue ID prefix (managed by `bd init`) -- `issue_id_mode` - ID generation mode: `hash` (default) or `counter` (sequential integers) -- `max_collision_prob` - Maximum collision probability for adaptive hash IDs (default: 0.25) -- `min_hash_length` - Minimum hash ID length (default: 4) -- `max_hash_length` - Maximum hash ID length (default: 8) -- `import.orphan_handling` - How to handle hierarchical issues with missing parents during import (default: `allow`) -- `import.path` - Input filename relative to `.beads/` for implied JSONL imports, including `bd init --from-jsonl` and empty-DB auto-import (default: `issues.jsonl`). Use a relative filename/path such as `beads.jsonl` so the import remains project-local and portable across machines. -- `export.auto` - Refresh the JSONL export after every write command (default: `false`). This is for viewers, interchange, and issue-level migration; it is not cross-machine sync and not a full database backup. -- `export.path` - Output filename relative to `.beads/` (default: `issues.jsonl`) -- `export.interval` - Minimum time between auto-exports (default: `60s`) -- `export.git-add` - Run `git add` on the export file after writing (default: `false`) -- `export.error_policy` - Error handling strategy for exports (default: `strict`) -- `export.retry_attempts` - Number of retry attempts for transient errors (default: 3) -- `export.retry_backoff_ms` - Initial backoff in milliseconds for retries (default: 100) -- `export.skip_encoding_errors` - Skip issues that fail JSON encoding (default: false) -- `export.write_manifest` - Write .manifest.json with export metadata (default: false) -- `auto_export.error_policy` - Override error policy for auto-exports (default: `best-effort`) -- `import.auto` - Master switch for automatic JSONL imports (default: `true`). Gates both the legacy hook fallback that imports JSONL after git merge/checkout when no Dolt remote is configured, and the empty-database recovery import that write commands run when `.beads/issues.jsonl` exists but the database is empty. Set to `false` to disable all auto-imports; explicit `bd import` always works. -- `sync.branch` - Name of the dedicated sync branch for beads data (see docs/PROTECTED_BRANCHES.md) -- `sync.require_confirmation_on_mass_delete` - Require interactive confirmation before pushing when >50% of issues vanish during a merge AND more than 5 issues existed before (default: `false`) - -**Upgrade note:** `export.auto` and `export.git-add` are opt-in. Older releases -briefly made `.beads/issues.jsonl` look like the default git-tracked source of -truth; current releases treat it as an optional export for viewers, -interchange, and issue-level migration. If your workflow depends on fresh JSONL -or on the pre-commit hook staging that file, set both values explicitly: - -```bash -bd config set export.auto true -bd config set export.git-add true -``` - -Use `bd dolt push` / `bd dolt pull` for cross-machine sync and `bd backup` for -restorable database backups. - -### Integration Namespaces - -Use these namespaces for external integrations: - -- `jira.*` - Jira integration settings -- `linear.*` - Linear integration settings -- `github.*` - GitHub integration settings -- `ado.*` - Azure DevOps integration settings -- `custom.*` - Custom integration settings - -### Status and Type Customization - -- `status.custom` - Custom issue statuses with optional categories (comma-separated) -- `types.custom` - Custom issue types (comma-separated) - -**Custom statuses** support category annotations that control behavior: - -```bash -# Format: name:category (category is optional) -bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done" - -# Categories: active, wip, done, frozen -# - active: shows in bd ready, included in default bd list -# - wip: excluded from bd ready, included in default bd list -# - done: excluded from bd ready AND default bd list (terminal) -# - frozen: excluded from bd ready AND default bd list (on hold) -# - (none): excluded from bd ready, included in default bd list (backward compatible) -``` - -**Custom types:** - -```bash -bd config set types.custom "agent,molecule,event" -``` - -See `bd statuses` and `bd types` commands to list all configured statuses and types. - -### Example: Sequential Counter IDs (issue_id_mode=counter) - -By default, beads generates hash-based IDs (e.g., `bd-a3f2`, `bd-7f3a8`). For projects that prefer -short sequential IDs (e.g., `bd-1`, `bd-2`, `bd-3`), enable counter mode: - -```bash -bd config set issue_id_mode counter -``` - -**Valid values:** - -| Value | Behavior | -|-------|----------| -| `hash` | (default) Hash-based IDs, adaptive length, collision-safe | -| `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, ... | - -**Counter mode behavior:** -- Each prefix (`bd`, `plug`, etc.) has its own independent counter -- Counter is stored atomically in the database; concurrent creates within a single Dolt session are safe -- Explicit `--id` flag always overrides counter mode (the counter is not incremented) - -**Enabling counter mode:** - -```bash -bd config set issue_id_mode counter - -# Now new issues get sequential IDs -bd create "First issue" -p 1 -# β†’ bd-1 - -bd create "Second issue" -p 2 -# β†’ bd-2 -``` - -**Migration warning:** If you switch an existing repository to counter mode, seed the counter -to avoid collisions with existing IDs. Find your highest current integer ID and set the counter -accordingly: - -```bash -# Check your highest existing sequential ID (if any) -bd list --json | jq -r '.[].id' | grep -E '^bd-[0-9]+$' | sort -t- -k2 -n | tail -1 - -# Seed the counter (e.g., if highest existing ID is bd-42) -bd config set issue_id_mode counter -# The counter auto-initializes at 0; new issues start at 1 -# If you already have bd-1 through bd-42, manually set counter: -# (no direct CLI for seeding β€” use bd dolt sql or create/delete N issues) -``` - -For fresh repositories switching to counter mode before any issues exist, no seeding is needed. - -**Per-prefix counter isolation:** - -Each issue prefix maintains its own counter independently. In multi-repo or routed setups, -`bd-*` issues and `plug-*` issues each start at 1: - -```bash -# Prefix "bd" and prefix "plug" have independent counters -bd create "Core task" -p 1 # β†’ bd-1 -bd create "Plugin task" -p 1 # β†’ plug-1 (if prefix is "plug") -``` - -**Tradeoff β€” hash vs. counter:** - -| | Hash IDs | Counter IDs | -|---|---|---| -| Human readability | Lower (e.g., `bd-a3f2`) | Higher (e.g., `bd-1`) | -| Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) | -| Predictability | Unpredictable | Sequential | -| Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs | - -Counter IDs are well-suited for linear project-management workflows and human-facing issue tracking. -Hash IDs are safer when multiple agents or branches create issues concurrently, since each hash is -independently unique without coordination. - -See [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) for full documentation on hash-based ID generation. - -### Example: Adaptive Hash ID Configuration - -```bash -# Configure adaptive ID lengths (see docs/ADAPTIVE_IDS.md) -# Default: 25% max collision probability -bd config set max_collision_prob "0.25" - -# Start with 4-char IDs, scale up as database grows -bd config set min_hash_length "4" -bd config set max_hash_length "8" - -# Stricter collision tolerance (1%) -bd config set max_collision_prob "0.01" - -# Force minimum 5-char IDs for consistency -bd config set min_hash_length "5" -``` - -See [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) for detailed documentation. - -### Example: Export Error Handling - -Controls how export operations handle errors when fetching issue data (labels, comments, dependencies). - -```bash -# Strict: Fail fast on any error (default for user-initiated exports) -bd config set export.error_policy "strict" - -# Best-effort: Skip failed operations with warnings (good for auto-export) -bd config set export.error_policy "best-effort" - -# Partial: Retry transient failures, skip persistent ones with manifest -bd config set export.error_policy "partial" -bd config set export.write_manifest "true" - -# Required-core: Fail on core data (issues/deps), skip enrichments (labels/comments) -bd config set export.error_policy "required-core" - -# Customize retry behavior -bd config set export.retry_attempts "5" -bd config set export.retry_backoff_ms "200" - -# Skip individual issues that fail JSON encoding -bd config set export.skip_encoding_errors "true" - -# Auto-export uses different policy (background operation) -bd config set auto_export.error_policy "best-effort" -``` - -**Policy details:** - -- **`strict`** (default) - Fail immediately on any error. Ensures complete exports but may block on transient issues like database locks. Best for critical exports and migrations. - -- **`best-effort`** - Skip failed batches with warnings. Continues export even if labels or comments fail to load. Best for auto-exports and background sync where availability matters more than completeness. - -- **`partial`** - Retry transient failures (3x by default), then skip with manifest file. Creates `.manifest.json` alongside JSONL documenting what succeeded/failed. Best for large databases with occasional corruption. - -- **`required-core`** - Fail on core data (issues, dependencies), skip enrichments (labels, comments) with warnings. Best when metadata is secondary to issue tracking. - -**When to use each mode:** - -- Use `strict` (default) for production backups and critical exports -- Use `best-effort` for auto-exports (default via `auto_export.error_policy`) -- Use `partial` when you need visibility into export completeness -- Use `required-core` when labels/comments are optional - -**Context-specific behavior:** - -User-initiated exports (`bd dolt push`, manual export commands) use `export.error_policy` (default: `strict`). - -Auto-exports (git hook sync) use `auto_export.error_policy` (default: `best-effort`), falling back to `export.error_policy` if not set. - -**Example: Different policies for different contexts:** - -```bash -# Critical project: strict everywhere -bd config set export.error_policy "strict" - -# Development project: strict user exports, permissive auto-exports -bd config set export.error_policy "strict" -bd config set auto_export.error_policy "best-effort" - -# Large database with occasional corruption -bd config set export.error_policy "partial" -bd config set export.write_manifest "true" -bd config set export.retry_attempts "5" -``` - -### Example: Import Orphan Handling - -Controls how imports handle hierarchical child issues when their parent is missing from the database: - -```bash -# Strictest: Fail import if parent is missing (safest, prevents orphans) -bd config set import.orphan_handling "strict" - -# Auto-resurrect: Search JSONL history and recreate missing parents as tombstones -bd config set import.orphan_handling "resurrect" - -# Skip: Skip orphaned issues with warning (partial import) -bd config set import.orphan_handling "skip" - -# Allow: Import orphans without validation (default, most permissive) -bd config set import.orphan_handling "allow" -``` - -**Mode details:** - -- **`strict`** - Fails immediately if a child's parent is missing. Use when database integrity is critical. -- **`resurrect`** - Searches for missing parents and recreates them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis. -- **`skip`** - Skips orphaned children with a warning. Partial import succeeds but some issues are excluded. -- **`allow`** - Imports orphans without parent validation. Most permissive. **This is the default** because it ensures all data is imported even if hierarchy is temporarily broken. - -These modes apply when bootstrapping a database with `bd init --from-jsonl` or when `bd dolt pull` merges remote data: - -```bash -# Override config for a single pull -bd config set import.orphan_handling "resurrect" -bd dolt pull # Respects import.orphan_handling setting -``` - -**When to use each mode:** - -- Use `allow` (default) for daily sync - ensures no data loss -- Use `resurrect` when pulling from remotes that had parent deletions -- Use `strict` only when you need to guarantee parent existence -- Use `skip` rarely - only when you want to selectively import a subset - -### Example: Sync Safety Options - -Controls for the sync branch workflow (see docs/PROTECTED_BRANCHES.md): - -```bash -# Configure sync branch (required for protected branch workflow) -bd config set sync.branch beads-sync - -# Enable mass deletion protection (optional, default: false) -# When enabled, if >50% of issues vanish during a merge AND more than 5 -# issues existed before the merge, bd dolt push will: -# 1. Show forensic info about vanished issues -# 2. Prompt for confirmation before pushing -bd config set sync.require_confirmation_on_mass_delete "true" -``` - -**When to enable `sync.require_confirmation_on_mass_delete`:** - -- Multi-user workflows where accidental mass deletions could propagate -- Critical projects where data loss prevention is paramount -- When you want manual review before pushing large changes - -**When to keep it disabled (default):** - -- Single-user workflows where you trust your local changes -- CI/CD pipelines that need non-interactive sync -- When you want hands-free automation - -### Example: Jira Integration - -```bash -# Configure Jira connection -bd config set jira.url "https://company.atlassian.net" -bd config set jira.project "PROJ" -bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated) -bd config set jira.api_token "YOUR_TOKEN" - -# Map bd statuses to Jira statuses -bd config set jira.status_map.open "To Do" -bd config set jira.status_map.in_progress "In Progress" -bd config set jira.status_map.closed "Done" - -# Map bd issue types to Jira issue types -bd config set jira.type_map.bug "Bug" -bd config set jira.type_map.feature "Story" -bd config set jira.type_map.task "Task" - -# Set Jira custom fields on pushed issues -bd config set jira.custom_fields.customfield_10042 '{"value":"AI Platform"}' -bd config set jira.custom_fields.Story.customfield_10042 '{"value":"AI Platform"}' -``` - -`jira.custom_fields.` applies to every issue pushed to Jira. -`jira.custom_fields..` applies only when the mapped Jira issue -type matches ``; per-type fields override global fields with the same -field key. Values beginning with `{` or `[` are sent as JSON, which is useful -for select-like fields. Other values are sent as strings. - -### Example: Linear Integration - -Linear integration provides bidirectional sync between bd and Linear via GraphQL API. - -**Required configuration:** - -```bash -# API Key (recommended: use environment variable to avoid git exposure) -export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # add to ~/.secrets or ~/.zshrc - -# Team ID (find in Linear team settings or URL) -bd config set linear.team_id "team-uuid-here" - -# Multiple team IDs (comma-separated; can also use LINEAR_TEAM_IDS env var) -bd config set linear.team_ids "uuid-team-1,uuid-team-2" -``` - -When `linear.team_ids` is set, `bd linear sync` fetches issues from all listed -teams. For push operations with multiple teams, use the `--team` flag to specify -the target. The singular `linear.team_id` is still supported for backward -compatibility. - -**Getting your Linear credentials:** - -1. **API Key**: Go to Linear β†’ Settings β†’ API β†’ Personal API keys β†’ Create key -2. **Team ID**: Go to Linear β†’ Settings β†’ General β†’ Team ID (or extract from URLs) - -**Priority mapping (Linear 0-4 β†’ Beads 0-4):** - -Linear and Beads both use 0-4 priority scales, but with different semantics: -- Linear: 0=no priority, 1=urgent, 2=high, 3=medium, 4=low -- Beads: 0=critical, 1=high, 2=medium, 3=low, 4=backlog - -Default mapping (configurable): - -```bash -bd config set linear.priority_map.0 4 # No priority -> Backlog -bd config set linear.priority_map.1 0 # Urgent -> Critical -bd config set linear.priority_map.2 1 # High -> High -bd config set linear.priority_map.3 2 # Medium -> Medium -bd config set linear.priority_map.4 3 # Low -> Low -``` - -**State mapping (Linear state types β†’ Beads statuses):** - -Map Linear workflow state types to Beads statuses: - -```bash -bd config set linear.state_map.backlog open -bd config set linear.state_map.unstarted open -bd config set linear.state_map.started in_progress -bd config set linear.state_map.completed closed -bd config set linear.state_map.canceled closed - -# For custom workflow states, use lowercase state name: -bd config set linear.state_map.in_review in_progress -bd config set linear.state_map.blocked blocked -bd config set linear.state_map.on_hold blocked -``` - -**Label to issue type mapping:** - -Infer bd issue type from Linear labels: - -```bash -bd config set linear.label_type_map.bug bug -bd config set linear.label_type_map.defect bug -bd config set linear.label_type_map.feature feature -bd config set linear.label_type_map.enhancement feature -bd config set linear.label_type_map.epic epic -bd config set linear.label_type_map.chore chore -bd config set linear.label_type_map.maintenance chore -bd config set linear.label_type_map.task task -``` - -**Relation type mapping (Linear relations β†’ Beads dependencies):** - -```bash -bd config set linear.relation_map.blocks blocks -bd config set linear.relation_map.blockedBy blocks -bd config set linear.relation_map.duplicate duplicates -bd config set linear.relation_map.related related -``` - -Relation import is opt-in when pulling: - -```bash -bd linear sync --pull --relations -``` - -**Sync commands:** - -```bash -# Bidirectional sync (pull then push, with conflict resolution) -bd linear sync - -# Pull only (import from Linear) -bd linear sync --pull - -# Pull only if data is stale (skip if fresh) -bd linear sync --pull-if-stale - -# Pull with custom staleness threshold (default 20m) -bd linear sync --pull-if-stale --threshold 5m - -# Pull issues and Linear relations as bd dependencies -bd linear sync --pull --relations - -# Pull and rebuild Linear project milestones as local epic parents -bd linear sync --pull --milestones - -# Push only (export to Linear) -bd linear sync --push - -# Dry run (preview without changes) -bd linear sync --dry-run - -# Conflict resolution options -bd linear sync --prefer-local # Local version wins on conflicts -bd linear sync --prefer-linear # Linear version wins on conflicts -# Default: newer timestamp wins - -# Check sync status -bd linear status -``` - -**Staleness detection:** - -After each successful pull, `bd` writes the current timestamp to `.beads/last_pull` (a local-only, per-machine file covered by the `.beads/.gitignore` template). This enables opt-in staleness detection on `bd linear sync`: - -- **`--pull-if-stale`**: Only pull if data is older than the threshold (default 20m). When data is fresh, prints "Linear data is fresh" and exits. In `--json` mode, includes `"is_fresh": true/false`. -- **`--threshold`**: Override the default 20-minute staleness threshold (e.g., `--threshold 5m`). -- **Debounce**: A 5-minute debounce prevents agent loops β€” if a pull completed within the last 5 minutes, data is always treated as fresh regardless of the threshold. - -To keep Linear data fresh in agent sessions, run `bd linear sync --pull-if-stale` explicitly (e.g., from a session-start hook). `bd prime` and other core commands do not contact Linear. - -**Automatic sync tracking:** - -The `linear.last_sync` config key is automatically updated after each sync, enabling incremental sync (only fetch issues updated since last sync). - -### Example: GitHub Integration - -```bash -# Configure GitHub connection -bd config set github.org "myorg" -bd config set github.repo "myrepo" -bd config set github.token "YOUR_TOKEN" - -# Map bd labels to GitHub labels -bd config set github.label_map.bug "bug" -bd config set github.label_map.feature "enhancement" -``` - -### Example: Azure DevOps (ADO) Integration - -Azure DevOps integration provides bidirectional sync between bd and ADO work items. - -**Required configuration:** - -```bash -# Personal access token (can also use AZURE_DEVOPS_PAT environment variable) -bd config set ado.pat "YOUR_PAT" - -# Organization name (can also use AZURE_DEVOPS_ORG environment variable) -bd config set ado.org "myorg" - -# Project name (can also use AZURE_DEVOPS_PROJECT environment variable) -bd config set ado.project "MyProject" - -# Multiple projects (comma-separated; can also use AZURE_DEVOPS_PROJECTS env var) -bd config set ado.projects "Project1,Project2" -``` - -When `ado.projects` is set, `bd ado sync` fetches work items from all listed -projects in a single WIQL query. The singular `ado.project` is still supported -for backward compatibility. - -**Optional configuration:** - -```bash -# Custom base URL for Azure DevOps Server (on-prem) instances -# (can also use AZURE_DEVOPS_URL environment variable) -# When set, ado.org is not required β€” the URL replaces the default dev.azure.com base. -bd config set ado.url "https://ado.internal.example.com/DefaultCollection" -``` - -**Getting your Azure DevOps PAT:** - -1. Go to Azure DevOps β†’ User Settings (top-right icon) β†’ Personal access tokens -2. Click "New Token" -3. Select the organization and set an expiration -4. Grant **Work Items: Read & Write** scope (minimum for sync) -5. Copy the token β€” it is only shown once - -**State mapping (ADO Agile template defaults β†’ Beads statuses):** - -ADO uses process-template-specific states (Agile, Scrum, CMMI). The defaults -use the Agile template. Override with `ado.state_map.*` for your process: - -```bash -# Default Agile mapping (built-in, no config needed): -# New β†’ open -# Active β†’ in_progress -# Resolved β†’ closed -# Closed β†’ closed -# Removed β†’ deferred - -# Override for Scrum template: -bd config set ado.state_map.open "New" -bd config set ado.state_map.in_progress "Committed" -bd config set ado.state_map.blocked "Committed" -bd config set ado.state_map.deferred "Removed" -bd config set ado.state_map.closed "Done" -``` - -**Type mapping (ADO work item types ↔ Beads issue types):** - -```bash -# Default mapping (built-in, no config needed): -# Bug β†’ bug -# User Story β†’ feature -# Product Backlog Item β†’ feature -# Task β†’ task -# Epic β†’ epic - -# Override for your process template: -bd config set ado.type_map.bug "Bug" -bd config set ado.type_map.feature "Feature" -bd config set ado.type_map.task "Task" -bd config set ado.type_map.epic "Epic" -bd config set ado.type_map.chore "Task" -``` - -**Priority mapping (ADO 1-4 β†’ Beads 0-4):** - -ADO uses a 1-4 scale; Beads uses 0-4. The mapping is: -- ADO 1 (Critical) β†’ Beads 0 (Critical) -- ADO 2 (High) β†’ Beads 1 (High) -- ADO 3 (Medium) β†’ Beads 2 (Medium) -- ADO 4 (Low) β†’ Beads 3 (Low) -- Beads 4 (Backlog) β†’ ADO 4 (lossy: backlog collapses to low) - -Priority mapping is not configurable β€” it is handled automatically. - -**Environment variables:** - -All ADO config keys have environment variable equivalents: - -| Config Key | Environment Variable | -|----------------|--------------------------| -| `ado.pat` | `AZURE_DEVOPS_PAT` | -| `ado.org` | `AZURE_DEVOPS_ORG` | -| `ado.project` | `AZURE_DEVOPS_PROJECT` | -| `ado.projects` | `AZURE_DEVOPS_PROJECTS` | -| `ado.url` | `AZURE_DEVOPS_URL` | - -Environment variables take effect when the corresponding `bd config` key is not set. - -**Sync commands:** - -```bash -# Bidirectional sync (pull then push, with conflict resolution) -bd ado sync - -# Pull only (import from Azure DevOps) -bd ado sync --pull-only - -# Push only (export to Azure DevOps) -bd ado sync --push-only - -# Dry run (preview without changes) -bd ado sync --dry-run - -# Conflict resolution options -bd ado sync --prefer-local # Local version wins on conflicts -bd ado sync --prefer-ado # Azure DevOps version wins on conflicts -bd ado sync --prefer-newer # Most recent version wins (default) - -# Check sync status and configuration -bd ado status - -# List accessible projects (useful for finding your project name) -bd ado projects --json -``` - -**Automatic sync tracking:** - -The `ado.last_sync` config key is automatically updated after each sync, enabling incremental sync (only fetch work items updated since last sync). - -## Use in Scripts - -Configuration is designed for scripting. Use `--json` for machine-readable output: - -```bash -#!/bin/bash - -# Get Jira URL -JIRA_URL=$(bd config get --json jira.url | jq -r '.value') - -# Get all config and extract multiple values -bd config list --json | jq -r '.["jira.project"]' -``` - -Example Python script: -```python -import json -import subprocess - -def get_config(key): - result = subprocess.run( - ["bd", "config", "get", "--json", key], - capture_output=True, - text=True - ) - data = json.loads(result.stdout) - return data["value"] - -def list_config(): - result = subprocess.run( - ["bd", "config", "list", "--json"], - capture_output=True, - text=True - ) - return json.loads(result.stdout) - -# Use in integration -jira_url = get_config("jira.url") -jira_project = get_config("jira.project") -``` - -## Best Practices - -1. **Use namespaces**: Prefix keys with integration name (e.g., `jira.*`, `linear.*`) -2. **Hierarchical keys**: Use dots for structure (e.g., `jira.status_map.open`) -3. **Document your keys**: Add comments in integration scripts -4. **Security**: Store tokens in config, but ensure `.beads/dolt/` and `.beads/*.db` are in `.gitignore` (bd does this automatically) -5. **Per-project**: Configuration is project-specific, so each repo can have different settings - -## Integration with bd Commands - -Some bd commands automatically use configuration: - -- `bd admin compact` uses `compact_tier1_days`, `compact_tier1_dep_levels`, etc. -- `bd init` sets `issue_prefix` - -External integration scripts can read configuration to sync with Jira, Linear, GitHub, etc. - -## See Also - -- [README.md](../README.md) - Main documentation -- [ADVANCED.md](ADVANCED.md) - Extensible Database section and other advanced topics diff --git a/docs/COPILOT_INTEGRATION.md b/docs/COPILOT_INTEGRATION.md deleted file mode 100644 index 45d198623..000000000 --- a/docs/COPILOT_INTEGRATION.md +++ /dev/null @@ -1,264 +0,0 @@ -# GitHub Copilot VS Code MCP Integration Guide - -This guide explains how to use beads with GitHub Copilot in **VS Code via MCP**. - -For the **GitHub Copilot CLI** integration installed by `bd setup copilot`, see [COPILOT_CLI_INTEGRATION.md](COPILOT_CLI_INTEGRATION.md). - -## Overview - -Beads provides a persistent, structured memory for coding agents through the MCP (Model Context Protocol) server. With Copilot, you can use natural language to create, update, and track issues without leaving your editor. - -**Important:** Beads is a system-wide CLI tool. You install it once and use it in any project. Do NOT clone the beads repository into your project. - -## Prerequisites - -- VS Code 1.96+ with GitHub Copilot extension -- GitHub Copilot subscription (Individual, Business, or Enterprise) -- beads CLI installed (`brew install beads` or `npm install -g @beads/bd`) -- Python 3.10+ OR uv package manager - -## Quick Setup - -### Step 1: Install beads-mcp - -```bash -# Using uv (recommended) -uv tool install beads-mcp - -# Or using pip -pip install beads-mcp - -# Or using pipx -pipx install beads-mcp -``` - -### Step 2: Configure VS Code MCP - -Create or edit `.vscode/mcp.json` in your project: - -```json -{ - "servers": { - "beads": { - "command": "beads-mcp" - } - } -} -``` - -**For all projects:** Add to VS Code user-level MCP config: - -| Platform | Path | -|----------|------| -| macOS | `~/Library/Application Support/Code/User/mcp.json` | -| Linux | `~/.config/Code/User/mcp.json` | -| Windows | `%APPDATA%\Code\User\mcp.json` | - -```json -{ - "servers": { - "beads": { - "command": "beads-mcp", - "args": [] - } - } -} -``` - -### Step 3: Initialize beads in your project - -```bash -cd your-project -bd init --quiet -``` - -This creates a `.beads/` directory with the issue database. The init wizard will ask about git hooksβ€”these are optional and you can skip them if unfamiliar. - -### Step 4: Add Copilot instructions (optional but recommended) - -Create `.github/copilot-instructions.md`: - -```markdown -## Issue Tracking - -This project uses **bd (beads)** for issue tracking. -Run `bd prime` for workflow context. - -**Quick reference:** -- `bd ready` - Find unblocked work -- `bd create "Title" --type task --priority 2` - Create issue -- `bd close ` - Complete work -- `bd dolt push` - Push changes to remote (run at session end) -``` - -### Step 5: Restart VS Code - -Reload the VS Code window for MCP configuration to take effect. - -## Using Beads with Copilot - -### Natural Language Commands - -With MCP configured, ask Copilot Chat: - -| You say | Copilot does | -|---------|--------------| -| "What issues are ready to work on?" | Calls `beads_ready` | -| "Create a bug for the login timeout" | Calls `beads_create` with type=bug | -| "Show me issue bd-42" | Calls `beads_show` | -| "Mark bd-42 as complete" | Calls `beads_close` | -| "What's blocking bd-15?" | Calls `beads_dep_tree` | - -### MCP Tools Reference - -| Tool | Description | Example | -|------|-------------|---------| -| `beads_ready` | List unblocked issues | "What can I work on?" | -| `beads_list` | List issues with filters | "Show all open bugs" | -| `beads_create` | Create new issue | "Create a task for refactoring" | -| `beads_show` | Show issue details | "Show bd-42 details" | -| `beads_update` | Update issue fields | "Set bd-42 to in progress" | -| `beads_close` | Close an issue | "Complete bd-42" | -| `beads_dolt_push` | Push changes to remote | "Push my changes" | -| `beads_dep_add` | Add dependency | "bd-99 blocks bd-42" | -| `beads_dep_tree` | Show dependency tree | "What depends on bd-42?" | - -### Example Workflow - -``` -You: What issues are ready to work on? - -Copilot: [Calls beads_ready] -There are 3 issues ready: -1. [P1] bd-42: Fix authentication timeout -2. [P2] bd-99: Add password reset flow -3. [P3] bd-17: Update API documentation - -You: Let me work on bd-42. Claim it. - -Copilot: [Calls beads_claim] -Claimed bd-42 and started work. - -You: [... work on the code ...] - -You: I found a related bug - the session token isn't being refreshed. - Create a bug for that, linked to bd-42. - -Copilot: [Calls beads_create] -Created bd-103: Session token not refreshed -Linked as discovered-from bd-42. - -You: Done with bd-42. Close it with reason "Fixed timeout handling" - -Copilot: [Calls beads_close] -Closed bd-42: Fixed timeout handling - -You: Push my changes to the remote - -Copilot: [Calls beads_dolt_push] -Pushed: 2 issues updated, synced to Dolt remote. -``` - -## CLI vs MCP: When to Use Each - -| Approach | Best For | Trade-offs | -|----------|----------|------------| -| **MCP (Copilot Chat)** | Natural language, discovery | Higher token overhead | -| **CLI (Terminal)** | Scripting, precision, speed | Requires terminal context | - -You can use both! MCP for conversational work, CLI for quick commands. - -## Troubleshooting - -### MCP tools not appearing in Copilot - -1. **Check VS Code version** - MCP requires VS Code 1.96+ -2. **Verify mcp.json syntax** - JSON must be valid -3. **Check beads-mcp is installed:** - ```bash - which beads-mcp - beads-mcp --version - ``` -4. **Reload VS Code** - MCP config requires window reload -5. **Check Output panel** - Look for MCP-related errors - -### "beads-mcp: command not found" - -The MCP server isn't in your PATH: - -```bash -# If installed with uv -export PATH="$HOME/.local/bin:$PATH" - -# If installed with pip, find it -pip show beads-mcp | grep Location - -# Reinstall if needed -uv tool install beads-mcp --force -``` - -### "No beads database found" - -Initialize beads in your project: - -```bash -cd your-project -bd init --quiet -``` - -### Changes not persisting - -Push changes at end of session: - -```bash -bd dolt push -``` - -Or ask Copilot: "Push my beads changes to the remote" - -### Organization policies blocking MCP - -For Copilot Enterprise, your organization must enable "MCP servers in Copilot" policy. Contact your admin if MCP tools don't appear. - -## FAQ - -### Do I need to clone the beads repository? - -**No.** Beads is a system-wide CLI tool. You install it once (via Homebrew, npm, or pip) and use it in any project. The `.beads/` directory in your project only contains the issue database, not beads itself. - -### What are the git hooks and are they safe? - -When you run `bd init`, beads can install git hooks that: -- **post-merge**: Import issues when you pull -- **pre-push**: Sync issues before you push - -These hooks are safeβ€”they only read/write the `.beads/` directory and never modify your code. You can opt out with `bd init --no-hooks` or skip them during the interactive setup. - -### Can I use beads without Copilot? - -Yes! Beads works with: -- Terminal (direct CLI) -- Claude Code -- Cursor -- Aider -- Any editor with MCP or shell access - -### MCP vs CLI - which should I use? - -Use **MCP** when you want natural language interaction through Copilot Chat. -Use **CLI** when you want speed, scripting, or precise control. - -Both approaches work with the same databaseβ€”use whichever fits your workflow. - -### Does this work with Copilot in other editors? - -This guide is for VS Code. For other editors: -- **JetBrains IDEs**: Check if MCP is supported, config may differ -- **Neovim**: Use CLI integration instead - -## See Also - -- [MCP Server Documentation](../website/docs/integrations/mcp-server.md) -- [CLI Reference](QUICKSTART.md) -- [Installation Guide](INSTALLING.md) -- [Agent Instructions](../AGENT_INSTRUCTIONS.md) diff --git a/docs/DOLT-BACKEND.md b/docs/DOLT-BACKEND.md index a6b2430fb..7dae8805e 100644 --- a/docs/DOLT-BACKEND.md +++ b/docs/DOLT-BACKEND.md @@ -3,6 +3,6 @@ The canonical Dolt backend guide is [architecture/dolt.md](architecture/dolt.md). The previous long-form duplicate of this file has been staged at -[staged-for-removal/DOLT-BACKEND.md](../engdocs/staged-for-removal/DOLT-BACKEND.md). +[staged-for-removal/DOLT-BACKEND.md](https://github.com/gastownhall/beads/blob/main/engdocs/staged-for-removal/DOLT-BACKEND.md). Rescue content from that staged copy only if it is verified against current code or observed CLI behaviour and belongs in the canonical guide. diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index c56d24b1d..000000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,515 +0,0 @@ -# Frequently Asked Questions - -Common questions about bd (beads) and how to use it effectively. - -## General Questions - -### What is bd? - -bd is a lightweight, Dolt-powered issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, so agents and humans can collaborate from the same task graph. - -### Why not just use GitHub Issues? - -GitHub Issues + gh CLI can approximate some features, but fundamentally cannot replicate what AI agents need: - -**Key Differentiators:** - -1. **Typed Dependencies with Semantics** - - bd: Four types (`blocks`, `related`, `parent-child`, `discovered-from`) with different behaviors - - GH: Only "blocks/blocked by" links, no semantic enforcement, no `discovered-from` for agent work discovery - -2. **Deterministic Ready-Work Detection** - - bd: `bd ready` computes transitive blocking offline in ~10ms, no network required - - GH: No built-in "ready" concept; would require custom GraphQL + sync service + ongoing maintenance - -3. **Offline-First, Branch-Scoped Task Memory** - - bd: Works offline, issues live on branches, hash IDs prevent collisions on merge - - GH: Cloud-first, requires network/auth, global per-repo, no branch-scoped task state - -4. **AI-Resolvable Conflicts & Duplicate Merge** - - bd: Automatic collision resolution, duplicate merge with dependency consolidation and reference rewriting - - GH: Manual close-as-duplicate, no safe bulk merge, no cross-reference updates - -5. **Version-Controlled SQL Database** - - bd: Full SQL queries against local Dolt database with native version control - - GH: No local database; would need to mirror data externally - -6. **Agent-Native APIs** - - bd: Consistent `--json` on all commands, dedicated MCP server with auto workspace detection - - GH: Mixed JSON/text output, GraphQL requires custom queries, no agent-focused MCP layer - -**When to use each:** GitHub Issues excels for human teams in web UI with cross-repo dashboards and integrations. bd excels for AI agents needing offline, version-controlled task memory with graph semantics and deterministic queries. - -See [GitHub issue #125](https://github.com/gastownhall/beads/issues/125) for detailed comparison. - -### How is this different from Taskwarrior? - -Taskwarrior is excellent for personal task management, but bd is built for AI agents: - -- **Explicit agent semantics**: `discovered-from` dependency type, `bd ready` for queue management -- **JSON-first design**: Every command has `--json` output -- **Built-in sync**: Version-controlled storage with native push/pull, no separate sync server to run -- **Dolt merge**: Cell-level merge with AI-resolvable conflicts -- **SQL database**: Full SQL queries against Dolt database - -### Can I use bd without AI agents? - -Absolutely! bd is a great CLI issue tracker for humans too. The `bd ready` command is useful for anyone managing dependencies. Think of it as "Taskwarrior meets git." - -### Is this production-ready? - -**Current status: Active development with 1.x releases** - -bd is in active development and being dogfooded on real projects. The core functionality (create, update, dependencies, ready work, Dolt-backed sync) is stable and well-tested. However: - -- **CLI/API changes still happen** - command flags and data formats can evolve -- **Safe for development/internal projects** - use normal backup and sync hygiene -- **Data is portable** - `bd export` produces human-readable JSONL for migration -- **Rapid iteration** - expect frequent updates and improvements - -**When to use bd:** -- βœ… AI-assisted development workflows -- βœ… Internal team projects -- βœ… Personal productivity with dependency tracking -- βœ… Experimenting with agent-first tools - -**When to wait:** -- Mission-critical production systems without a tested backup/restore plan -- Large enterprise deployments that need formal compatibility guarantees -- Long-term archival as the only system of record - -Follow the repo for updates and compatibility notes. - -## Usage Questions - -### Why hash-based IDs? Why not sequential? - -**Hash IDs eliminate collisions** when multiple agents or branches create issues concurrently. - -**The problem with sequential IDs:** -```bash -# Branch A creates bd-10 -git checkout -b feature-auth -bd create "Add OAuth" # Sequential ID: bd-10 - -# Branch B also creates bd-10 -git checkout -b feature-payments -bd create "Add Stripe" # Collision! Same sequential ID: bd-10 - -# Merge conflict! -git merge feature-auth # Two different issues, same ID -``` - -**Hash IDs solve this:** -```bash -# Branch A -bd create "Add OAuth" # Hash ID: bd-a1b2 (from random UUID) - -# Branch B -bd create "Add Stripe" # Hash ID: bd-f14c (different UUID, different hash) - -# Clean merge! -git merge feature-auth # No collision, different IDs -``` - -**Progressive length scaling:** -- 4 chars (0-500 issues): `bd-a1b2` -- 5 chars (500-1,500 issues): `bd-f14c3` -- 6 chars (1,500+ issues): `bd-3e7a5b` - -bd automatically extends hash length as your database grows to maintain low collision probability. - -### What are hierarchical child IDs? - -**Hierarchical IDs** (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`) provide human-readable structure for epics and their subtasks. - -**Example:** -```bash -# Create epic (generates parent hash) -bd create "Auth System" -t epic -p 1 -# Returns: bd-a3f8e9 - -# Create children (auto-numbered .1, .2, .3) -bd create "Login UI" -p 1 # bd-a3f8e9.1 -bd create "Validation" -p 1 # bd-a3f8e9.2 -bd create "Tests" -p 1 # bd-a3f8e9.3 -``` - -**Benefits:** -- Parent hash ensures unique namespace (no cross-epic collisions) -- Sequential child IDs are human-friendly -- Up to 3 levels of nesting supported -- Clear visual grouping in issue lists - -**When to use:** -- Epics with multiple related tasks -- Large features with sub-features -- Work breakdown structures - -**When NOT to use:** -- Simple one-off tasks (use regular hash IDs) -- Cross-cutting dependencies (use `bd dep add` instead) - -### Should I run bd init or have my agent do it? - -**Either works!** But use the right flag: - -**Humans:** -```bash -bd init # Interactive - prompts for git hooks -``` - -**Agents:** -```bash -bd init --quiet # Non-interactive - auto-installs hooks, no prompts -``` - -**Workflow for humans:** -```bash -# Clone existing project with bd: -git clone -cd -bd init # Creates Dolt database, pulls from remote if configured - -# Or initialize new project: -cd ~/my-project -bd init # Creates .beads/, sets up Dolt database -git add .beads/ -git commit -m "Initialize beads" -``` - -**Workflow for agents setting up repos:** -```bash -git clone -cd -bd init --quiet # No prompts, auto-installs hooks -bd ready --json # Start using bd normally -``` - -### Do I need to run export/import manually? - -**No! Dolt handles storage and versioning natively.** - -All writes go directly to the Dolt database and are automatically committed to Dolt history. To sync with Dolt remotes: - -```bash -bd init # Auto-configures git origin as the Dolt remote when present -# or: bd init --remote http://myserver:7007/mydb # Explicit non-origin remote -bd dolt push # Push changes to Dolt remote -bd dolt pull # Pull changes from Dolt remote -``` - -The `bd export` command exists for issue portability and interchange. For backup and restore, use `bd backup init ` / `bd backup sync` to push Dolt-native backups, and `bd backup restore ` to restore from them. None of these are needed for day-to-day Dolt sync. - -For the full conceptual model β€” why the local Dolt database is the source of truth, what `issues.jsonl` is and is not for, and which sync patterns to avoid β€” see [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md). - -### What if my database feels stale after a colleague pushes changes? - -Pull from the Dolt remote: - -```bash -bd dolt pull # Fetch and merge updates from Dolt remote -bd ready # Shows fresh data -``` - -For federation setups, use: -```bash -bd federation sync # Sync with all configured peers -``` - -### Can I track issues for multiple projects? - -**Yes! Each project is completely isolated.** bd uses project-local databases: - -```bash -cd ~/project1 && bd init --prefix proj1 -cd ~/project2 && bd init --prefix proj2 -``` - -Each project gets its own `.beads/` directory with its own Dolt database. bd auto-discovers the correct database based on your current directory (walks up like git). - -**Multi-project scenarios work seamlessly:** -- Multiple agents working on different projects simultaneously - no conflicts -- Same machine, different repos - each finds its own `.beads/` automatically -- Agents in subdirectories - bd walks up to find the project root (like git) -- **Per-project Dolt servers** (default) - each project gets its own Dolt server -- **Shared Dolt server** (opt-in) - all projects share a single server for reduced resource usage - -**Limitation:** Issues cannot reference issues in other projects. Each database is isolated by design. If you need cross-project tracking, initialize bd in a parent directory that contains both projects. - -**Example:** Multiple agents, multiple projects, same machine: -```bash -# Agent 1 working on web app -cd ~/work/webapp && bd ready --json # Uses ~/work/webapp/.beads/ database "webapp" - -# Agent 2 working on API -cd ~/work/api && bd ready --json # Uses ~/work/api/.beads/ database "api" - -# No conflicts! Completely isolated databases. -``` - -**Shared server mode** (recommended for machines with 2+ projects): -```bash -# Enable shared server - single Dolt process serves all projects -export BEADS_DOLT_SHARED_SERVER=1 # add to shell profile for machine-wide -# Or per-project: bd dolt set shared-server true -``` - -**Architecture:** By default, bd uses per-project Dolt servers (like LSP/language servers). With shared server mode enabled, a single server at `~/.beads/shared-server/` handles all projects, each using its own database. See [DOLT.md](DOLT.md) for details. - -### What happens if two agents work on the same issue? - -With Dolt server mode, concurrent writes are handled natively. For distributed setups, Dolt's cell-level merge resolves most conflicts automatically. To prevent conflicts: - -- Have agents claim work with `bd update --claim` -- Query by assignee: `bd ready --assignee agent-name` -- Review git diffs before merging - -For true multi-agent coordination, use Dolt server mode (`bd dolt start`) which supports concurrent writes natively. For distributed setups, use Dolt federation for peer-to-peer sync. - -### Why Dolt instead of plain files? - -- βœ… **Version-controlled SQL**: Full SQL queries with native version control -- βœ… **Cell-level merge**: Concurrent changes merge automatically at the field level -- βœ… **Multi-writer**: Server mode supports concurrent agents -- βœ… **Native branching**: Dolt branches independent of git branches -- βœ… **Portable**: `bd export` produces JSONL for migration and interoperability - -See [DOLT.md](DOLT.md) for detailed analysis. - -### How do I handle merge conflicts? - -When two developers create new issues: - -```diff - {"id":"bd-1","title":"First issue",...} - {"id":"bd-2","title":"Second issue",...} -+{"id":"bd-3","title":"From branch A",...} -+{"id":"bd-4","title":"From branch B",...} -``` - -Git may show a conflict, but resolution is simple: **keep both lines** (both changes are compatible). - -**With hash-based IDs (v0.20.1+), same-ID scenarios are updates, not collisions:** - -If you import an issue with the same ID but different fields, bd treats it as an update to the existing issue. This is normal behavior - hash IDs remain stable, so same ID = same issue being updated. - -Dolt handles merge conflicts natively with cell-level merge. Use `bd vc conflicts` to view and resolve any conflicts after pulling. - -## Migration Questions - -### How do I migrate from GitHub Issues / Jira / Linear? - -We don't have automated migration tools yet, but you can: - -1. Export issues from your current tracker (usually CSV or JSON) -2. Write a simple script to convert to bd's JSONL format -3. Place the JSONL file at `.beads/issues.jsonl` and run `bd init --from-jsonl` - -See [examples/](../examples/) for scripting patterns. Contributions welcome! - -### Can I export back to GitHub Issues / Jira? - -Not yet built-in, but you can: - -1. Export from bd: `bd export -o issues.jsonl --json` -2. Write a script to convert JSONL to your target format -3. Use the target system's API to import - -The [CONFIG.md](CONFIG.md) guide shows how to store integration settings. Contributions for standard exporters welcome! - -## Performance Questions - -### How does bd handle scale? - -bd uses Dolt (a version-controlled SQL database), which handles millions of rows efficiently. For a typical project with thousands of issues: - -- Commands complete in <100ms -- Full-text search is instant -- Dependency graphs traverse quickly -- Dolt database stays compact with garbage collection - -For extremely large projects (100k+ issues), you might want to filter exports or use multiple databases per component. - -### What if my database gets too large? - -Use compaction to remove old closed issues: - -```bash -# Preview what would be compacted -bd admin compact --dry-run --all - -# Compact issues closed more than 90 days ago -bd admin compact --days 90 - -# Run Dolt garbage collection -cd .beads/dolt && dolt gc -``` - -Or split your project into multiple databases: -```bash -cd ~/project/frontend && bd init --prefix fe -cd ~/project/backend && bd init --prefix be -``` - -## Use Case Questions - -### Can I use bd for non-code projects? - -Sure! bd is just an issue tracker. Use it for: - -- Writing projects (chapters as issues, dependencies as outlines) -- Research projects (papers, experiments, dependencies) -- Home projects (renovations with blocking tasks) -- Any workflow with dependencies - -The agent-friendly design works for any AI-assisted workflow. - -### Can I use bd with multiple AI agents simultaneously? - -Yes! Each agent can: - -1. Query ready work: `bd ready --assignee agent-name` -2. Assign issues: `bd update --assignee agent-name` -3. Start work (as assigned agent): `bd update --status in_progress` -4. Create discovered work: `bd create "Found issue" --deps discovered-from:` -5. Sync via `bd dolt push` / `bd dolt pull` - -Note: In orchestrated workflows, assignment is usually done by an orchestrator. -If the issue is already assigned, start with `bd update --status in_progress`. -If an agent picks work directly, use atomic `bd update --claim --assignee agent-name`. - -bd's version-controlled storage means agents work independently and merge their changes like developers do, with cell-level merge resolving most conflicts automatically. - -### Does bd work offline? - -Yes! bd is designed for offline-first operation: - -- All queries run against local Dolt database -- No network required for any commands -- Sync happens via `bd dolt push` / `bd dolt pull` when you're online -- Full functionality available without internet - -This makes bd ideal for: -- Working on planes/trains -- Unstable network connections -- Air-gapped environments -- Privacy-sensitive projects - -## Technical Questions - -### What dependencies does bd have? - -bd is a single static binary with no runtime dependencies: - -- **Language**: Go 1.24+ -- **Database**: Dolt (server mode) -- **Optional**: Git (for version control of project code) - -That's it! No PostgreSQL, no Redis, no Docker, no node_modules. - -### Can I extend bd's database? - -With the Dolt backend, use `bd query` for direct SQL access or build integrations using `bd --json` CLI output. - -### Does bd support Windows? - -Yes! bd has native Windows support (v0.9.0+): - -- No MSYS or MinGW required -- PowerShell install script -- Works with Windows paths and filesystem -- Dolt server uses TCP instead of Unix sockets - -See [INSTALLING.md](INSTALLING.md#windows-11) for details. - -### Can I use bd with git worktrees? - -Yes! Dolt handles worktrees natively. Use embedded mode if the Dolt server is not needed: - -```bash -bd dolt set mode embedded -bd ready -bd create "Fix bug" -p 1 -``` - -See [WORKTREES.md](WORKTREES.md) for details. - -### Why did beads create worktrees in my .git directory? - -Older versions of beads created git worktrees for a **sync-branch** feature that has since been removed. Dolt now stores data under `refs/dolt/data`, separate from standard Git refs, so a separate branch is no longer needed. - -If you have leftover worktrees from an older version, you can safely remove them: - -```bash -rm -rf .git/beads-worktrees -rm -rf .git/worktrees/beads-* -git worktree prune -``` - -**To disable sync-branch (stop worktree creation):** - -```bash -bd config set sync.branch "" -``` - -See [WORKTREES.md#legacy-cleanup](WORKTREES.md#legacy-cleanup) for full details. - -### What's the difference between database corruption and ID collisions? - -bd handles two distinct types of integrity issues: - -**1. Logical Consistency (Collision Resolution)** - -The hash/fingerprint/collision architecture prevents: -- **ID collisions**: Same ID assigned to different issues (e.g., from parallel workers or branch merges) -- **Wrong prefix bugs**: Issues created with incorrect prefix due to config mismatch -- **Merge conflicts**: Branch divergence creating conflicting data - -**Solution**: Hash-based IDs (v0.20+) eliminate collisions. Different issues automatically get different IDs. - -**2. Physical Database Corruption** - -Database corruption can occur from: -- **Disk/hardware failures**: Power loss, disk errors, filesystem corruption -- **Concurrent writes**: Multiple processes writing to the database simultaneously - -**Solution**: Rebuild from Dolt remote or a backup export: -```bash -rm -rf .beads/dolt -bd init -bd dolt pull # Pull from Dolt remote if configured -``` - -**Key Difference**: Collision resolution fixes logical issues in the data. Physical corruption requires restoring from Dolt remotes or backup exports. - -**For multi-writer scenarios**: Use Dolt server mode (`bd dolt set mode server`) to allow concurrent access from multiple processes. - -## Getting Help - -### Where can I get more help? - -- **Documentation**: [README.md](../README.md), [QUICKSTART.md](QUICKSTART.md), [ADVANCED.md](ADVANCED.md) -- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) -- **Examples**: [examples/](../examples/) -- **GitHub Issues**: [Report bugs or request features](https://github.com/gastownhall/beads/issues) -- **GitHub Discussions**: [Ask questions](https://github.com/gastownhall/beads/discussions) - -### How can I contribute? - -Contributions are welcome! See [CONTRIBUTING.md](../CONTRIBUTING.md) for: - -- Code contribution guidelines -- How to run tests -- Development workflow -- Issue and PR templates - -### Where's the roadmap? - -The roadmap lives in bd itself! Run: - -```bash -bd list --priority 0 --priority 1 --json -``` - -Or check the GitHub Issues for feature requests and planned improvements. diff --git a/docs/GIT_INTEGRATION.md b/docs/GIT_INTEGRATION.md index 01e0bb105..113f889fb 100644 --- a/docs/GIT_INTEGRATION.md +++ b/docs/GIT_INTEGRATION.md @@ -1,354 +1,7 @@ -# Git Integration Guide +# Git Integration -**For:** AI agents and developers managing bd git workflows - -## Overview - -bd integrates with git for worktree support and protected branch workflows. The Dolt backend handles all data storage and versioning natively. - -## Git Worktrees - -Beads has comprehensive Git worktree compatibility with shared database architecture. - -### How It Works - -Git worktrees share the same `.git` directory and `.beads` database: -- All worktrees use the same `.beads/dolt/` database in the main repository -- Database discovery prioritizes main repository location -- Worktree-aware git operations prevent conflicts - -### Worktree-Aware Features - -**Database Discovery:** -- Resolves the active workspace using `BEADS_DIR`, worktree fallback, and shared main-repo `.beads` -- Falls back to worktree-local search if needed -- Prevents database duplication across worktrees -- Use `bd where` as the authoritative check; local `./.beads` may be absent in pure worktree or redirected setups - -**Git Operations:** -- Worktree-aware repository root detection -- Proper handling of git directory vs git common directory -- Safe concurrent access to shared database (use server mode for multi-writer) - -## Protected Branch Workflows - -**Note:** Beads data is stored in Dolt under `refs/dolt/data`, separate from standard Git refs. This means beads does not commit to any Git branch, so protected branch workflows are not affected. - -Sync with remotes using Dolt's native push/pull: - -```bash -bd init # Auto-wires git origin as a Dolt remote when origin exists -bd dolt push # Push changes to Dolt remote -bd dolt pull # Pull changes from Dolt remote -``` - -### Daily Workflow (Unchanged for Agents) - -```bash -# Agents work normally - no changes needed! -bd create "Fix authentication" -t bug -p 1 -bd update bd-a1b2 --claim -bd close bd-a1b2 "Fixed" -``` - -### Merging to Main (Humans) - -```bash -# Check what's changed -bd dolt show - -# Option 1: Create pull request -git push origin beads-sync -# Then create PR on GitHub/GitLab - -# Option 2: Direct merge (if allowed) -git merge beads-sync -``` - -### Benefits - -- Works with protected `main` branches -- No disruption to agent workflows -- Platform-agnostic (works on any git platform) -- Backward compatible (opt-in via config) - -See [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) for complete setup guide, troubleshooting, and examples. - -## Branchless Workflows (Jujutsu / jj) - -Beads works with branchless VCS tools like [Jujutsu (jj)](https://martinvonz.github.io/jj/). Since beads data is stored in Dolt (not git branches), there is no dependency on the "current branch" concept. - -### What Works Without Hooks - -All core beads functionality works without git hooks: - -| Feature | Hooks Required? | Notes | -|---------|----------------|-------| -| `bd create`, `bd update`, `bd close` | No | Core CRUD uses Dolt directly | -| `bd ready`, `bd list`, `bd show` | No | Read-only queries | -| `bd dolt push` / `bd dolt pull` | No | Dolt-native sync, independent of git | -| `bd onboard`, `bd doctor` | No | Diagnostics and onboarding | -| Agent identity trailers | Yes | `prepare-commit-msg` hook adds `Executed-By:` to commits | -| Hook chaining | Yes | Preserves existing pre-commit, post-merge hooks | - -**To skip hooks entirely during init:** - -```bash -bd init --skip-hooks -``` - -### What Works Without AGENTS.md - -The AGENTS.md file generated by `bd init` provides AI agent instructions (including "Landing the Plane" push/pull workflow). If you manage your own agent instructions or don't want beads to modify tracked files: - -```bash -bd init --skip-agents # Skip AGENTS.md and Claude/Codex setup generation -bd init --stealth # Full invisible mode (also skips hooks + agents) -``` - -### Jujutsu Setup - -**Colocated repos** (`jj git init --colocate`): Git hooks work normally. Beads installs simplified hooks (no staging logic). - -**Pure jj repos** (no git): Since jj doesn't have native hooks yet, set up push aliases: - -```toml -# ~/.config/jj/config.toml -[aliases] -push = ["util", "exec", "--", "sh", "-c", "bd dolt commit && bd dolt push && jj git push \"$@\"", ""] -``` - -### Merge Conflicts - -Configure jj to use beads' merge driver for `.beads/issues.jsonl`: - -```toml -# ~/.config/jj/config.toml -[merge-tools.beads-merge] -program = "bd" -merge-args = ["merge", "$output", "$base", "$left", "$right"] -merge-conflict-exit-codes = [1] -``` - -Then resolve with: `jj resolve --tool=beads-merge .beads/issues.jsonl` - -## Git Hooks - -### External Hook Manager Support - -bd detects and integrates with these external git hook managers: - -- **[lefthook](https://lefthook.dev/)** β€” YAML/TOML/JSON config -- **[husky](https://typicode.github.io/husky/)** β€” `.husky/` directory scripts -- **[pre-commit](https://pre-commit.com/)** β€” `.pre-commit-config.yaml` -- **[prek](https://prek.j178.dev/)** β€” Rust-based pre-commit alternative (same config) -- **[hk](https://hk.jdx.dev/)** β€” Fast hook manager using Pkl config -- **[overcommit](https://github.com/sds/overcommit)** β€” Ruby-based (detection only) -- **[simple-git-hooks](https://github.com/toplenboren/simple-git-hooks)** β€” Lightweight JS (detection only) - -When an external hook manager is detected, `bd hooks install` uses `--chain` to preserve existing hooks. - -#### hk Integration Example - -Add bd hooks to your `hk.pkl`: - -```pkl -hooks { - ["pre-commit"] { - steps { - ["bd-pre-commit"] { - check = "bd hooks run pre-commit" - } - } - } - ["post-merge"] { - steps { - ["bd-post-merge"] { - check = "bd hooks run post-merge" - } - } - } - ["pre-push"] { - steps { - ["bd-pre-push"] { - check = "bd hooks run pre-push \"$@\"" - } - } - } -} -``` - -### Installation - -```bash -# Install hooks -bd hooks install --beads -``` - -### What Gets Installed - -**pre-commit hook:** -- Runs pre-commit checks for beads data consistency - -**post-merge hook:** -- Runs chained user hooks, then uses JSONL import only as a legacy fallback - when no Dolt remote is configured. With `sync.remote` configured, use - `bd dolt pull` for canonical issue sync. - -### Hook Timeout - -The beads hook shim wraps `bd hooks run` with an OS-level `timeout` to prevent hooks from hanging git operations indefinitely. The default timeout is **300 seconds** (5 minutes), which accommodates repos with chained pre-commit pipelines (e.g., eslint, prettier, TypeScript compilation). - -If your chained hooks need more time, override the timeout with the `BEADS_HOOK_TIMEOUT` environment variable: - -```bash -# Set a longer timeout (in seconds) -export BEADS_HOOK_TIMEOUT=600 # 10 minutes - -# Or set it per-invocation -BEADS_HOOK_TIMEOUT=600 git commit -m "..." -``` - -When the timeout is reached, beads prints a warning and allows the git operation to proceed (the commit/push is not blocked). - -### Hook Implementation Details - -#### Hook Installation (`cmd/bd/hooks.go`) - -The `installHooks()` function: -- Writes embedded hook scripts to the `.git/hooks/` directory -- Creates the hooks directory with `os.MkdirAll()` if needed -- Backs up existing hooks with `.backup` extension (unless `--force` flag used) -- Sets execute permissions (0755) on installed hooks -- Supports shared mode via `--shared` flag (installs to `.beads-hooks/` instead) - -#### Git Directory Resolution - -**Critical for worktree support:** The `getGitDir()` helper uses `git rev-parse --git-dir` to resolve the actual git directory: - -```go -// Returns ".git" in normal repos -// Returns "/path/to/shared/.git" in git worktrees -gitDir, err := getGitDir() -``` - -In **normal repositories**, `.git` is a directory containing the git internals. -In **git worktrees**, `.git` is a file containing `gitdir: /path/to/actual/git/dir`. - -#### Hook Detection (`cmd/bd/init.go`) - -The `detectExistingHooks()` function scans for existing hooks and classifies them: - -- **bd hooks**: Identified by "bd (beads) pre-commit hook" comment in content -- **pre-commit framework hooks**: Detected by "pre-commit framework" or "pre-commit.com" in content -- **Custom hooks**: Any other existing hook - -## Multi-Workspace Sync - -### Fork-Based Pattern - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ OSS Contrib │─────▢│ Planning Repo β”‚ -β”‚ (Fork) β”‚ β”‚ (.beads/dolt/) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”‚ PR - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Upstream Repo β”‚ -β”‚ (no .beads/) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -**Best for:** -- Open source contributors -- Solo developers -- Private task tracking on public repos - -**Setup:** -```bash -bd init --contributor # Interactive wizard -``` - -### Team Branch Pattern - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Team Member │────┐ -β”‚ (main) β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Team Member │─▢│ Shared Repo β”‚ -β”‚ (main) β”‚ β”‚ (beads-sync) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -**Best for:** -- Teams on protected branches -- Managed git workflows -- Review-before-merge policies - -**Setup:** -```bash -bd init --team # Interactive wizard -``` - -See [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for complete guide. - -## Git Configuration Best Practices - -### Recommended .gitignore - -``` -# Dolt database (not tracked in git) -.beads/dolt/ - -``` - -### Git LFS Considerations - -The Dolt database directory (`.beads/dolt/`) should be gitignored, not tracked via LFS or regular git. - -## Custom Merge Driver - -bd includes a built-in merge driver for resolving conflicts in `.beads/issues.jsonl` files. This replaces the standalone `beads-merge` binary that was previously maintained in a separate repository. - -### Alternative: Standalone beads-merge Binary (Deprecated) - -> **⚠️ Deprecated:** The standalone `beads-merge` binary (previously hosted at `github.com/neongreen/mono`) is no longer maintained and may be incompatible with current versions of bd. Use `bd merge` instead. - -The built-in `bd merge` command provides the same functionality: - -```bash -bd merge -``` - -### Jujutsu Integration - -> See also: [Branchless Workflows](#branchless-workflows-jujutsu--jj) for a complete guide. - -**For [Jujutsu](https://martinvonz.github.io/jj/) users**, add to `~/.config/jj/config.toml`: - -```toml -[merge-tools.beads-merge] -program = "bd" -merge-args = ["merge", "$output", "$base", "$left", "$right"] -merge-conflict-exit-codes = [1] -``` - -Then resolve conflicts with: - -```bash -jj resolve --tool=beads-merge .beads/issues.jsonl -``` - -This configures Jujutsu to invoke `bd merge` as its merge tool, restricted to `.beads/issues.jsonl` (since it only handles beads data conflicts, not general file conflicts). - -## See Also - -- [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md) - How beads data syncs across machines (Dolt remotes vs. git; what JSONL-via-git is and is not for) -- [AGENTS.md](../AGENTS.md) - Main agent workflow guide -- [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) - Protected branch workflows -- [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) - Multi-repo patterns +This guide moved to [reference/git-integration.md](reference/git-integration.md) +as part of the Mintlify docs site under `docs/`. This pointer stays because +released `bd` binaries link to `docs/GIT_INTEGRATION.md` on GitHub β€” including +the `#branchless-workflows-jujutsu--jj` section, now at +[reference/git-integration.md](reference/git-integration.md#branchless-workflows-jujutsu--jj). diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index eb786c0fa..23dc2e540 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -1,640 +1,6 @@ - -# Installing bd +# Installing beads -Complete installation guide for all platforms. - -## Components Overview - -Beads has several components - here's what they are and when you need them: - -| Component | What It Is | When You Need It | -|-----------|------------|------------------| -| **bd CLI** | Core command-line tool | Always - this is the foundation | -| **Claude Code Plugin** | Slash commands + enhanced UX | Optional - if you want `/beads:ready`, `/beads:create` commands | -| **MCP Server (beads-mcp)** | Model Context Protocol interface | Only for MCP-only environments (Claude Desktop, Amp) | - -**How they relate:** -- The **bd CLI** is the core - install it first via Homebrew, npm, or script -- The **Plugin** enhances Claude Code with slash commands but *requires* the CLI installed -- The **MCP server** is an *alternative* to the CLI for environments without shell access - -**Important:** Beads is installed system-wide, not cloned into your project. The `.beads/` directory in your project only contains the issue database. - -**Typical setups:** - -| Environment | What to Install | -|-------------|-----------------| -| Claude Code, Cursor, Windsurf | bd CLI (+ optional Plugin for Claude Code) | -| GitHub Copilot (VS Code) | bd CLI + MCP server | -| Claude Desktop (no shell) | MCP server only | -| Terminal / scripts | bd CLI only | -| CI/CD pipelines | bd CLI only | - -**Are they mutually exclusive?** No - you can have CLI + Plugin + MCP all installed. They don't conflict. But most users only need the CLI. - -## Quick Install (Recommended) - -### Homebrew (macOS/Linux) - -```bash -brew install beads -``` - -Homebrew core's `beads` formula is the supported Homebrew package. If you -previously installed the old tap formula as `bd`, migrate to the core formula: - - -```bash -brew uninstall bd -brew untap gastownhall/beads 2>/dev/null || true -brew untap steveyegge/beads 2>/dev/null || true -brew install beads -``` - -**Why Homebrew?** -- βœ… Simple one-command install -- βœ… Automatic updates via `brew upgrade` -- βœ… No need to install Go -- βœ… Handles PATH setup automatically - -### [Mise-en-place](https://mise.jdx.dev) (macOS/Linux/Windows) - -You can install beads using mise from the latest GitHub release: - -```bash -mise install github:gastownhall/beads -mise use -g github:gastownhall/beads -``` - -**NOTE**: The `-g` enables beads globally. To enable project-specific versions, omit that. - -**Why Mise?** -- βœ… Same as Homebrew: simple, updates via `mise up`, works without Go, handles PATH -- βœ… Supports all platforms -- βœ… Always the latest release -- βœ… May optionally use a different release version for specific projects - -Mise's Go backend follows the same caveats as `go install`; prefer the release backend above. - -### Quick Install Script (All Platforms) - -```bash -curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -``` - -The installer will: -- Detect your platform (macOS/Linux/FreeBSD, amd64/arm64) -- Verify downloaded release archives against release `checksums.txt` -- Fall back to the supported `go install` modes if Go is available -- Fall back to building from source if needed -- Guide you through PATH setup if necessary - -On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in: - -```bash -BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -``` - -### Comparison of Installation Methods - -| Method | Best For | Updates | Prerequisites | Notes | -|--------|----------|---------|---------------|-------| -| **Homebrew** | macOS/Linux users | `brew upgrade beads` | Homebrew | Recommended. Handles everything automatically | -| **npm** | JS/Node.js projects | `npm update -g @beads/bd` | Node.js | Convenient if npm is your ecosystem | -| **bun** | JS/Bun.js projects | `bun install -g --trust @beads/bd` | Bun.js | Convenient if bun is your ecosystem | -| **Install script** | Quick setup, CI/CD | Re-run script | curl, bash | Good for automation and one-liners | -| **go install (nocgo)** | Go developers, simplest install | Re-run command | Go 1.24+ | **Server-mode only** (no embedded Dolt) | -| **go install (cgo)** | Go developers wanting embedded mode | Re-run command | Go 1.24+, C compiler | Full embedded-Dolt support | -| **From source** | Contributors only | `git pull && go build` | Go, git | Full control, can modify code | -| **AUR (Arch)** | Arch Linux users | `yay -Syu` | yay/paru | Community-maintained | - -**TL;DR:** Use Homebrew if available. Use npm if you're in a Node.js environment. Use the script for quick one-off installs or CI. - -### A note on `go install` capability - -`go install` supports **two build modes** that give different capabilities: - -- **Nocgo (simplest, default in this doc):** `CGO_ENABLED=0 go install ...`. Works on any machine with a Go toolchain, no C compiler needed. Produces a **server-mode-only** binary β€” you must run an external `dolt sql-server` and use `bd init --server`. See [DOLT.md](DOLT.md) for server-mode setup. -- **Cgo (embedded-capable):** `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ...`. Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend β€” `bd init` Just Works. - -Use the `github.com/steveyegge/beads` path for `go install`. The repository now lives under `gastownhall/beads`, but released Go modules still declare `github.com/steveyegge/beads` for compatibility. - -If you don't have a preference, `brew install beads` / `install.sh` give you the embedded-capable build with no fuss. - -## Platform-Specific Installation - -### macOS - -**Via Homebrew** (recommended): -```bash -brew install beads -``` - -**Via go install** (server-mode only, simplest): -```bash -CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest -# Then: bd init --server (requires a running dolt sql-server) -``` - -**Via go install** (embedded-capable, needs Xcode CLI tools): -```bash -CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest -``` - -**From source**: -```bash -git clone https://github.com/gastownhall/beads -cd beads -make build # uses gms_pure_go tag and CGO -sudo mv bd /usr/local/bin/ -``` - -### Linux - -**Via Homebrew** (works on Linux too): -```bash -brew install beads -``` - -**Arch Linux** (AUR): -```bash -# Install from AUR -yay -S beads-git -# or -paru -S beads-git -``` - -Thanks to [@v4rgas](https://github.com/v4rgas) for maintaining the AUR package! - -**Via go install** (server-mode only, simplest): -```bash -CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest -# Then: bd init --server (requires a running dolt sql-server) -``` - -**Via go install** (embedded-capable, needs gcc): -```bash -CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest -``` - -**From source**: -```bash -git clone https://github.com/gastownhall/beads -cd beads -make build # uses gms_pure_go tag and CGO -sudo mv bd /usr/local/bin/ -``` - -### FreeBSD - -**Via Quick Install Script**: -```bash -curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -``` - -**Via go install** (server-mode only, simplest): -```bash -CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest -``` - -### Windows 11 - -Beads now ships with native Windows supportβ€”no MSYS or MinGW required. - -**Prerequisites:** -- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`) -- Git for Windows - -**Via PowerShell script**: -```pwsh -irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex -``` - -The script installs a prebuilt Windows release if available and verifies the downloaded ZIP checksum against release `checksums.txt`. Go is only required for `go install` or building from source. - -**Via go install** (server-mode only, simplest): -```pwsh -$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest -# Then: bd init --server (requires a running dolt sql-server) -``` - -This produces a server-mode-only binary with no C compiler requirement β€” the fastest path to a working `bd` on Windows. - -**Via go install** (embedded-capable, needs MinGW): -```pwsh -$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest -``` - -Requires MinGW-w64 gcc on your PATH. ICU is **not** required β€” `gms_pure_go` selects Go's stdlib `regexp`. - -**From source**: -```pwsh -git clone https://github.com/gastownhall/beads -cd beads -make build # uses gms_pure_go tag and CGO -Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\ -``` - -The `-tags gms_pure_go` flag tells go-mysql-server to use Go's stdlib regexp instead of ICU. - -**Verify installation**: -```pwsh -bd version -``` - -**Windows notes:** -- The Dolt server listens on a loopback TCP endpoint -- Allow `bd.exe` loopback traffic through any host firewall - -## Build Dependencies (Contributors Only) - -> **Note:** These dependencies are only needed if you build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely. - -Building from source requires a C compiler (for CGO / embedded Dolt). **ICU is -not required** -- all builds use the `gms_pure_go` tag which selects Go's -stdlib `regexp` instead of ICU regex. See [ICU-POLICY.md](../engdocs/ICU-POLICY.md) for -details. - -macOS (Homebrew): -```bash -brew install zstd -``` - -Linux (Debian/Ubuntu): -```bash -sudo apt-get install -y libzstd-dev -``` - -Linux (Fedora/RHEL): -```bash -sudo dnf install -y libzstd-devel -``` - -> **For maintainers only:** If you intentionally need to run -> `scripts/test-icu-path.sh` (which exercises the leftover ICU code path), -> install ICU headers: -> `brew install icu4c` (macOS) or `sudo apt-get install -y libicu-dev` (Linux). -> This is not needed for normal development. - -## IDE and Editor Integrations - -### CLI + Hooks (Recommended for Claude Code) - -**The recommended approach** for Claude Code, Cursor, Windsurf, and other editors with shell access: - -```bash -# 1. Install bd CLI (see Quick Install above) -brew install beads - -# 2. Initialize in your project -cd your-project -bd init --quiet - -# 3. Setup editor integration (choose one) -bd setup claude # Claude Code - installs SessionStart/PreCompact hooks -bd setup copilot # GitHub Copilot CLI - creates .copilot-plugin/plugin.json + .github/copilot-instructions.md -bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc -bd setup aider # Aider - creates .aider.conf.yml -bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks -bd setup factory # Factory.ai Droid - creates/updates AGENTS.md -bd setup mux # Mux - creates/updates AGENTS.md -``` - -**How it works:** -- `bd init` creates or updates `AGENTS.md` and installs project Claude/Codex integrations by default unless you use `--skip-agents` or `--stealth` -- Editor hooks/rules inject `bd prime` automatically on session start -- Codex 0.129.0+ uses native `/hooks`: SessionStart injects `bd prime`, compact hooks mark context stale, and the next prompt after compaction refreshes Beads context once -- `bd prime` provides ~1-2k tokens of workflow context -- You use `bd` CLI commands directly -- Git hooks (installed by `bd init`) refresh exports and legacy fallbacks; `bd dolt push/pull` syncs the database -- `bd onboard` prints the small manual snippet for unsupported agents or custom instruction files - -**Why this is recommended:** -- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas -- **Lower latency** - Direct CLI calls, no MCP protocol overhead -- **Universal** - Works with any editor that has shell access -- **More sustainable** - Less compute per request - -**Verify installation:** -```bash -bd setup claude --check # Check Claude Code integration -bd setup copilot --check # Check GitHub Copilot CLI project integration -bd setup cursor --check # Check Cursor integration -bd setup aider --check # Check Aider integration -bd setup codex --check # Check Codex integration -bd setup factory --check # Check Factory.ai integration -bd setup mux --check # Check Mux integration -``` - -### Claude Code Plugin (Optional) - -For enhanced UX with slash commands: - -```bash -# In Claude Code -/plugin marketplace add gastownhall/beads -/plugin install beads -# Restart Claude Code -``` - -The plugin adds: -- Slash commands: `/beads:ready`, `/beads:create`, `/beads:show`, `/beads:update`, `/beads:close`, etc. -- Task agent for autonomous execution - -See [PLUGIN.md](PLUGIN.md) for complete plugin documentation. - -### GitHub Copilot (VS Code) - -For VS Code with GitHub Copilot: - -1. **Install beads-mcp:** - ```bash - uv tool install beads-mcp - ``` - -2. **Configure MCP** - Create `.vscode/mcp.json` in your project: - ```json - { - "servers": { - "beads": { - "command": "beads-mcp" - } - } - } - ``` - - **For all projects:** Add to VS Code user-level MCP config: - - | Platform | Path | - |----------|------| - | macOS | `~/Library/Application Support/Code/User/mcp.json` | - | Linux | `~/.config/Code/User/mcp.json` | - | Windows | `%APPDATA%\Code\User\mcp.json` | - - ```json - { - "servers": { - "beads": { - "command": "beads-mcp", - "args": [] - } - } - } - ``` - -3. **Initialize project:** - ```bash - bd init --quiet - ``` - -4. **Reload VS Code** - -See [COPILOT_INTEGRATION.md](COPILOT_INTEGRATION.md) for complete setup guide. - -### GitHub Copilot CLI - -For the GitHub Copilot CLI terminal integration: - -```bash -bd setup copilot # Install project Copilot plugin + repository instructions -bd setup copilot --check # Verify the project integration files exist -``` - -This setup is currently project-scoped only. It writes: - -- `.copilot-plugin/plugin.json` -- `.github/copilot-instructions.md` - -There is no separate `--global` or `--project` mode for Copilot today, and it does not manage `~/.copilot/...` paths. - -See [COPILOT_CLI_INTEGRATION.md](COPILOT_CLI_INTEGRATION.md) for the full guide. - -### MCP Server (Alternative - for MCP-only environments) - -**Use MCP only when CLI is unavailable** (Claude Desktop, Sourcegraph Amp without shell): - -```bash -# Using uv (recommended) -uv tool install beads-mcp - -# Or using pip -pip install beads-mcp -``` - -**Configuration for Claude Desktop** (macOS): - -Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: - -```json -{ - "mcpServers": { - "beads": { - "command": "beads-mcp" - } - } -} -``` - -**Configuration for Sourcegraph Amp**: - -Add to your MCP settings: - -```json -{ - "beads": { - "command": "beads-mcp", - "args": [] - } -} -``` - -**Trade-offs:** -- βœ… Works in MCP-only environments -- ❌ Higher context overhead (MCP schemas add 10-50k tokens) -- ❌ Additional latency from MCP protocol - -See [integrations/beads-mcp/README.md](../integrations/beads-mcp/README.md) for detailed MCP server documentation. - -## Verifying Installation - -After installing, verify bd is working: - -```bash -bd version -bd help -``` - -## Troubleshooting Installation - -For additional troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). - -### `bd: command not found` - -bd is not in your PATH. Either: - -```bash -# Check if installed -go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd - -# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) -export PATH="$PATH:$(go env GOPATH)/bin" - -# Or reinstall (server-mode only, no C compiler needed) -CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest -``` - -### `zsh: killed bd` or crashes on macOS - -Some users report crashes when running `bd init` or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues. - -**Workaround:** -```bash -# Install an embedded-capable build -CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest - -# Or if building from source -git clone https://github.com/gastownhall/beads -cd beads -CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd -sudo mv bd /usr/local/bin/ -``` - -If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please [file an issue](https://github.com/gastownhall/beads/issues). - -### Claude Code Plugin: MCP server fails to start - -If the Claude Code plugin's MCP server fails immediately after installation, it's likely that `uv` is not installed or not in your PATH. - -**Symptoms:** -- Plugin slash commands work, but MCP tools are unavailable -- Error logs show `command not found: uv` -- Server fails silently on startup - -**Solution:** -```bash -# Install uv -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Restart your shell or update PATH -source ~/.local/bin/env - -# Verify uv is available -which uv - -# Restart Claude Code -``` - -See the "Claude Code Plugin" section above for alternative installation methods (Homebrew, pip). - -## Next Steps - -After installation: - -1. **Initialize a project**: `cd your-project && bd init` -2. **Configure your agent**: `bd init` creates/updates `AGENTS.md` and installs project Claude/Codex integrations by default; run `bd setup --list` for richer integrations or `bd onboard` for a manual fallback snippet -3. **Learn the basics**: See [QUICKSTART.md](QUICKSTART.md) for a tutorial -4. **Explore examples**: Check out the [examples/](../examples/) directory - -## Updating bd - -Use the update command that matches how you installed `bd`. - -Upgrade checklist: - -1. With your current `bd`, sync remote-backed databases before installing the - new binary: - `bd dolt push` - `bd dolt pull` -2. Back up before migration: - `bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl` -3. Upgrade using the command for your install method below. -4. After upgrading: - `bd info --whats-new` - `bd hooks install` - `bd version` -5. If crossing a schema migration on a remote-backed database, only the - designated migrator runs: - `bd migrate --force` - `bd dolt push` - -Other clones should install the new binary and run `bd bootstrap`, not -independently migrate. For the full procedure, see -[Upgrading bd β€” remote-backed databases and multiple clones](../website/docs/getting-started/upgrading.md#remote-backed-databases-and-multiple-clones). - -### Quick Install Script (macOS/Linux/FreeBSD) - -```bash -curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -``` - -### PowerShell Installer (Windows) - -```pwsh -irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex -``` - -### Homebrew - -```bash -brew upgrade beads -``` - -### npm - -```bash -npm update -g @beads/bd -``` - -### bun - -```bash -bun install -g --trust @beads/bd -``` - -### go install - -Use whichever mode you installed with originally: - -```bash -# Server-mode only -CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest - -# Embedded-capable -CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest -``` - -### From source - -```bash -cd beads -git pull -make build -sudo mv bd /usr/local/bin/ -``` - -## After Upgrading (Recommended) - -```bash -bd info --whats-new -bd hooks install -bd version -``` - -If your database syncs to a Dolt remote (a single clone or several), upgrading -across a schema migration needs an explicit, ordered procedure β€” `bd` refuses -to silently migrate a remote-backed database, so replacing the binary alone is -not enough. See [Upgrading bd β€” remote-backed databases and multiple -clones](../website/docs/getting-started/upgrading.md#remote-backed-databases-and-multiple-clones). - -Prereleases (e.g. release candidates) are published only as GitHub prereleases -and are not pushed to the stable Homebrew/npm/PyPI channels, so `brew upgrade` -and friends will not move you onto them β€” fetch the prerelease build explicitly. - -## Uninstalling - -To completely remove Beads from a repository, see [UNINSTALLING.md](UNINSTALLING.md). +This guide moved to [getting-started/installation.md](getting-started/installation.md) +as part of the Mintlify docs site under `docs/`. This pointer stays because +released `bd` binaries reference `docs/INSTALLING.md` (for example in the +storage-backend comparison help). diff --git a/docs/MOLECULES.md b/docs/MOLECULES.md deleted file mode 100644 index af16a9d11..000000000 --- a/docs/MOLECULES.md +++ /dev/null @@ -1,290 +0,0 @@ -# Molecules: Work Graphs in Beads - -This doc explains how beads structures and executes work. Start here if you're building workflows. - -## TL;DR - -1. **Work = issues with dependencies.** That's it. No special types needed. -2. **Dependencies control execution.** `blocks` = sequential. No dep = parallel. -3. **Molecules are just epics.** Any epic with children is a molecule. Templates are optional. -4. **Bonding = adding dependencies.** `bd mol bond A B` creates a dependency between work graphs. -5. **Agents execute until blocked.** When all ready work is done, the workflow is complete. - -## The Execution Model - -### How Work Flows - -An agent picks up a molecule (epic with children). They execute ready children in parallel until everything closes: - -``` -epic-root (assigned to agent) -β”œβ”€β”€ child.1 (no deps β†’ ready) ← execute in parallel -β”œβ”€β”€ child.2 (no deps β†’ ready) ← execute in parallel -β”œβ”€β”€ child.3 (needs child.1) β†’ blocked until child.1 closes -└── child.4 (needs child.2, child.3) β†’ blocked until both close -``` - -**Ready work:** `bd ready` shows issues with no open blockers. -**Blocked work:** `bd blocked` shows what's waiting. - -### Dependency Types That Block - -| Type | Semantics | Use Case | -|------|-----------|----------| -| `blocks` | B can't start until A closes | Sequencing work | -| `parent-child` | If parent blocked, children blocked | Hierarchy (children parallel by default) | -| `conditional-blocks` | B runs only if A fails | Error handling paths | -| `waits-for` | B waits for all of A's children | Fanout gates | - -**Non-blocking types:** `related`, `discovered-from`, `replies-to` - these link issues without affecting execution. - -### Default Parallelism - -**Children are parallel by default.** Only explicit dependencies create sequence: - -```bash -# These three tasks run in PARALLEL (no deps between them) -bd create "Task A" -t task -bd create "Task B" -t task -bd create "Task C" -t task - -# Add dependency to make B wait for A -bd dep add # B depends on A (B needs A) -``` - -### Multi-Day Execution - -An agent works through a molecule by: -1. Getting ready work (`bd ready`) -2. Claiming it (`bd update --claim`) -3. Doing the work -4. Closing it (`bd close `) -5. Repeat until molecule is done - -If the molecule is blocked by another molecule: -- Agent either waits, or -- Agent continues into the blocking molecule (compound execution) - -**Bonding enables compound execution:** When you bond molecule A to molecule B, the agent can traverse both as one logical unit of work. - -## Molecules vs Epics - -**They're the same thing.** A molecule is just an epic (parent + children) with workflow semantics. - -| Term | Meaning | When to Use | -|------|---------|-------------| -| **Epic** | Parent issue with children | General term for hierarchical work | -| **Molecule** | Epic with execution intent | When discussing workflow traversal | -| **Proto** | Epic with `template` label | Reusable pattern (optional) | - -You can create molecules without protos - just create an epic and add children: - -```bash -bd create "Feature X" -t epic -bd create "Design" -t task --parent -bd create "Implement" -t task --parent -bd create "Test" -t task --parent -bd dep add # implement needs design -bd dep add # test needs implement -``` - -## Bonding: Connecting Work Graphs - -**Bond = create a dependency between two work graphs.** - -```bash -bd mol bond A B # B depends on A (sequential by default) -bd mol bond A B --type parallel # Organizational link, no blocking -bd mol bond A B --type conditional # B runs only if A fails -``` - -### What Bonding Does - -| Operands | What Happens | -|----------|--------------| -| epic + epic | Creates dependency edge between them | -| proto + epic | Spawns proto as new issues, attaches to epic | -| proto + proto | Creates compound template | - -### The Key Insight - -**Bonding lets agents traverse compound workflows.** When A blocks B: -- Completing A unblocks B -- Agent can continue from A into B seamlessly -- The compound work graph can span days - -This is how orchestrators run autonomous workflows - agents follow the dependency graph, handing off between sessions, until all work closes. - -Ordinary epics stay open when the last child closes. They become close-eligible -work that can be closed explicitly once the parent outcome is actually done. - -## Phase Metaphor (Templates) - -For reusable workflows, beads uses a chemistry metaphor: - -| Phase | Name | Storage | Synced | Purpose | -|-------|------|---------|--------|---------| -| **Solid** | Proto | `.beads/` | Yes | Frozen template | -| **Liquid** | Mol | `.beads/` | Yes | Active persistent work | -| **Vapor** | Wisp | `.beads/` (Wisp=true) | No | Ephemeral operations | - -### Phase Commands - -```bash -bd mol pour # Proto β†’ Mol (persistent instance) -bd mol wisp # Proto β†’ Wisp (ephemeral instance) -bd mol squash # Mol/Wisp β†’ Digest (permanent record) -bd mol burn # Wisp β†’ nothing (discard) -``` - -### When to Use Each Phase - -| Use Case | Phase | Why | -|----------|-------|-----| -| Feature work | Mol (pour) | Persists across sessions, audit trail | -| Patrol cycles | Wisp | Routine, no audit value | -| One-shot ops | Wisp | Scaffolding, not the work itself | -| Important discovery during wisp | Mol (--pour) | "This matters, save it" | - -## Common Patterns - -### Sequential Pipeline - -```bash -bd create "Pipeline" -t epic -bd create "Step 1" -t task --parent -bd create "Step 2" -t task --parent -bd create "Step 3" -t task --parent -bd dep add -bd dep add -``` - -### Parallel Fanout with Gate - -```bash -bd create "Process files" -t epic -bd create "File A" -t task --parent -bd create "File B" -t task --parent -bd create "File C" -t task --parent -bd create "Aggregate" -t task --parent -# Aggregate needs all three (waits-for gate) -bd dep add --type waits-for -``` - -### Dynamic Bonding (Christmas Ornament) - -When the number of children isn't known until runtime: - -```bash -# In a survey step, discover workers and bond arms dynamically -for worker in $(bd agent list); do - bd mol bond mol-worker-arm $PATROL_ID --ref arm-$worker --var name=$worker -done -``` - -Creates: -``` -patrol-x7k (wisp) -β”œβ”€β”€ preflight -β”œβ”€β”€ survey-workers -β”‚ β”œβ”€β”€ patrol-x7k.arm-ace (dynamically bonded) -β”‚ β”œβ”€β”€ patrol-x7k.arm-nux (dynamically bonded) -β”‚ └── patrol-x7k.arm-toast (dynamically bonded) -└── aggregate (waits for all arms) -``` - -## Agent Pitfalls - -### 1. Temporal Language Inverts Dependencies - -**Wrong:** "Phase 1 comes before Phase 2" β†’ `bd dep add phase1 phase2` -**Right:** "Phase 2 needs Phase 1" β†’ `bd dep add phase2 phase1` - -Use requirement language. Verify with `bd blocked`. - -### 2. Assuming Order = Sequence - -Numbered steps don't create sequence. Dependencies do: - -```bash -# These run in PARALLEL despite names -bd create "Step 1" ... -bd create "Step 2" ... -bd create "Step 3" ... - -# Add deps to sequence them -bd dep add step2 step1 -bd dep add step3 step2 -``` - -### 3. Forgetting to Close Work - -Blocked issues stay blocked forever if their blockers aren't closed. Always close completed work: - -```bash -bd close --reason "Done" -``` - -### 4. Orphaned Wisps - -Wisps accumulate if not squashed/burned: - -```bash -bd mol wisp list # Check for orphans -bd mol squash # Create digest -bd mol burn # Or discard -bd mol wisp gc # Garbage collect old wisps -bd mol wisp gc --closed --force # Purge all closed wisps -``` - -## Layer Cake Architecture - -For reference, here's how the layers stack: - -``` -Formulas (JSON compile-time macros) ← optional, for complex composition - ↓ -Protos (template issues) ← optional, for reusable patterns - ↓ -Molecules (bond, squash, burn) ← workflow operations - ↓ -Epics (parent-child, dependencies) ← DATA PLANE (the core) - ↓ -Issues (Dolt, version-controlled) ← STORAGE -``` - -**Most users only need the bottom two layers.** Protos and formulas are for reusable patterns and complex composition. - -## Commands Quick Reference - -### Execution - -```bash -bd ready # What's ready to work -bd blocked # What's blocked -bd update --claim -bd close -``` - -### Dependencies - -```bash -bd dep add # issue needs depends-on -bd dep tree # Show dependency tree -``` - -### Molecules - -```bash -bd mol pour --var k=v # Template β†’ persistent mol -bd mol wisp # Template β†’ ephemeral wisp -bd mol bond A B # Connect work graphs -bd mol squash # Compress to digest -bd mol burn # Discard without record -``` - -## Related Docs - -- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Full command reference -- [ARCHITECTURE.md](ARCHITECTURE.md) - System internals -- [../CLAUDE.md](../CLAUDE.md) - Quick agent reference diff --git a/docs/MULTI_REPO_AGENTS.md b/docs/MULTI_REPO_AGENTS.md deleted file mode 100644 index fd5df03ac..000000000 --- a/docs/MULTI_REPO_AGENTS.md +++ /dev/null @@ -1,419 +0,0 @@ -# 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 Dolt servers: - -```json -{ - "beads": { - "command": "beads-mcp", - "args": [] - } -} -``` - -The MCP server automatically: -- Detects current workspace from working directory -- Routes to correct per-project Dolt server -- Auto-starts Dolt server if not running -- Maintains complete database isolation - -**Architecture (default):** -``` -MCP Server (one instance) - ↓ -Per-Project Dolt Servers (one per workspace) - ↓ -Dolt Databases (complete isolation) -``` - -With **shared server mode** enabled (`BEADS_DOLT_SHARED_SERVER=1`), all projects -use a single Dolt server at `~/.beads/shared-server/`. Database isolation is -maintained via per-project database names (based on project prefix). - -### 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 from all configured Dolt databases -2. Aggregates into unified view -3. Maintains `source_repo` field for provenance -4. Routes issues back to correct databases - -## 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 dolt push -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 -``` - -### Server 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:** Commands fail right after a `bd` upgrade - -**Fix:** -```bash -bd version # Confirm active CLI version -bd doctor quick # Validate local installation health -``` - -## 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 -- βœ… Use `bd dolt push` to sync the shared Dolt database -- βœ… Use `bd dolt push` to ensure changes are committed/pushed -- βœ… Link related issues across repos with dependencies -- ❌ Don't delete `.beads/` - you lose all issue data - -### 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 Dolt servers) -- βœ… Check routing config before filing issues -- βœ… Use `bd info --json` to verify workspace state -- βœ… Run `bd dolt push` 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 local Dolt database (single-repo mode) -``` - -**With multi-repo config:** -```bash -bd create "Issue" -p 1 -# β†’ Auto-routed based on config -# β†’ Old issues in local database 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 + server status -bd info --json - -# Sample output: -{ - "database_path": "/Users/you/projects/myapp/.beads/dolt", - "config": { - "routing": { - "mode": "auto", - "maintainer": ".", - "contributor": "~/.beads-planning" - }, - "repos": { - "primary": ".", - "additional": ["~/repo1", "~/repo2"] - } - }, - "server": { - "running": true, - "pid": 12345, - "mode": "server" - } -} -``` - -## 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 -- **[ROUTING.md#multi-repo-hydration](ROUTING.md#multi-repo-hydration)** - Hydration layer internals -- **[AGENTS.md](../AGENTS.md)** - Main AI agent guide diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 38ed658b6..d71f1f866 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -2,7 +2,7 @@ **Canonical documentation:** [Quick Start (published)](https://gastownhall.github.io/beads/getting-started/quickstart) β€” browse the full tutorial with navigation and search. -**Source in this repo:** [website/docs/getting-started/quickstart.md](../website/docs/getting-started/quickstart.md) (what GitHub Pages builds from; the `docs/` copy here is a pointer for deep links and agents). +**Source in this repo:** [docs/getting-started/quickstart.md](getting-started/quickstart.md) (the Mintlify site source; this file is a pointer for old deep links and agents). ## Ultra-short path diff --git a/docs/ROUTING.md b/docs/ROUTING.md deleted file mode 100644 index df17f2b8e..000000000 --- a/docs/ROUTING.md +++ /dev/null @@ -1,242 +0,0 @@ -# Multi-Repo Auto-Routing - -This document describes the auto-routing feature that intelligently directs new issues to the appropriate repository based on user role. - -## Overview - -Auto-routing solves the OSS contributor problem: contributors want to plan work locally without polluting upstream PRs with planning issues. The routing layer automatically detects whether you're a maintainer or contributor and routes `bd create` to the appropriate repository. - -## User Role Detection - -### Strategy - -The routing system detects user role via: - -1. **Explicit git config** (highest priority): - ```bash - git config beads.role maintainer - # or - git config beads.role contributor - ``` - -2. **Push URL inspection** (automatic): - - SSH URLs (`git@github.com:user/repo.git`) β†’ Maintainer - - HTTPS with credentials β†’ Maintainer - - HTTPS without credentials β†’ Contributor - - No remote β†’ Contributor (fallback) - -### Examples - -```bash -# Maintainer (SSH access) -git remote add origin git@github.com:owner/repo.git -bd create "Fix bug" -p 1 -# β†’ Creates in current repo (.) - -# Contributor (HTTPS fork) -git remote add origin https://github.com/fork/repo.git -git remote add upstream https://github.com/owner/repo.git -bd create "Fix bug" -p 1 -# β†’ Creates in planning repo (~/.beads-planning by default) -``` - -## Configuration - -Routing is configured via the database config: - -```bash -# Auto-routing is disabled by default (routing.mode="") -# Enable with: -bd init --contributor -# OR manually: -bd config set routing.mode auto - -# Set default planning repo -bd config set routing.default "~/.beads-planning" - -# Set repo for maintainers (in auto mode) -bd config set routing.maintainer "." - -# Set repo for contributors (in auto mode) -bd config set routing.contributor "~/.beads-planning" -``` - -## CLI Usage - -### Auto-Routing - -```bash -# Let bd decide based on role -bd create "Fix authentication bug" -p 1 - -# Maintainer: creates in current repo (.) -# Contributor: creates in ~/.beads-planning -``` - -### Explicit Override - -```bash -# Force creation in specific repo (overrides auto-routing) -bd create "Fix bug" -p 1 --repo /path/to/repo -bd create "Add feature" -p 1 --repo ~/my-planning -``` - -## Discovered Issue Inheritance - -Issues created with `discovered-from` dependencies automatically inherit the 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 in auth" -p 1 --deps discovered-from:bd-abc -# β†’ Created with source_repo = "." (same as parent) -``` - -This ensures discovered work stays in the same repository as the parent task. - -## Multi-Repo Hydration - -**⚠️ Critical:** When using routing to separate repos, you must enable multi-repo hydration or routed issues won't appear in `bd list`. - -### The Problem - -Auto-routing writes issues to a separate repository (e.g., `~/.beads-planning`), but by default, `bd list` only shows issues from the current repository's database. Without hydration, routed issues are "invisible" even though they exist. - -### The Solution - -Add routing targets to `repos.additional` in `config.yaml`: - -```yaml -routing: - mode: auto - contributor: ~/.beads-planning -repos: - primary: "." - additional: - - ~/.beads-planning -``` - -### Automatic Setup - -`bd init --contributor` now automatically configures both routing AND hydration: - -```bash -cd ~/my-forked-repo -bd init --contributor - -# This sets up: -# 1. routing.mode=auto -# 2. routing.contributor=~/.beads-planning -# 3. repos.additional=[~/.beads-planning] -``` - -### Manual Setup (Advanced) - -If you configured routing before this feature, add hydration manually: - -```bash -# Add planning repo to hydration list -bd repo add ~/.beads-planning - -# Verify configuration -bd repo list -``` - -### How It Works - -Multi-repo hydration imports issues from all configured repos into the current database: - -1. **Dolt database as source of truth**: Each repo maintains its own Dolt database -2. **Periodic sync**: Beads syncs from `repos.additional` every sync cycle -3. **Source tracking**: Each issue tagged with `source_repo` field -4. **Unified view**: `bd list` shows issues from all repos - -### Requirements - -**For optimal hydration, start Dolt servers in all repos:** - -```bash -# In main repo -bd dolt start - -# In planning repo -cd ~/.beads-planning -bd dolt start -``` - -Without running servers, hydration only sees old data. - -### Troubleshooting - -Run `bd doctor` to check for configuration issues: - -```bash -bd doctor - -# Checks: -# - routing.mode=auto with routing targets but repos.additional not configured -# - Routing targets not in repos.additional list -# - Dolt servers not running in hydrated repos -``` - -**Common Issues:** - -1. **Routed issues not appearing in bd list** - - **Cause:** `repos.additional` not configured - - **Fix:** `bd repo add ` - -2. **Issues appear but data is stale** - - **Cause:** Dolt server not running in target repo - - **Fix:** `cd && bd dolt start` - -3. **After upgrading, routed issues missing** - - **Cause:** Upgraded before hydration was automatic - - **Fix:** `bd repo add ` to enable hydration manually - -## Backward Compatibility - -- **Single-repo workflows unchanged**: If no multi-repo config exists, all issues go to current repo -- **Explicit --repo always wins**: `--repo` flag overrides any auto-routing -- **No schema changes**: Routing is pure config-based, no database migrations - -## Implementation - -**Key Files:** -- `internal/routing/routing.go` - Role detection and routing logic -- `internal/routing/routing_test.go` - Unit tests -- `cmd/bd/create.go` - Integration with create command -- `routing_integration_test.go` - End-to-end tests - -**API:** - -```go -// Detect user role based on git configuration -func DetectUserRole(repoPath string) (UserRole, error) - -// Determine target repo based on config and role -func DetermineTargetRepo(config *RoutingConfig, userRole UserRole, repoPath string) string -``` - -## Testing - -```bash -# Run routing tests -go test -v -run TestRouting - -# Tests cover: -# - Maintainer detection (git config) -# - Contributor detection (fork remotes) -# - SSH vs HTTPS remote detection -# - Explicit --repo override -# - End-to-end multi-repo workflow -``` - -## Future Enhancements - -See [bd-k58](https://github.com/gastownhall/beads/issues/k58) for proposal workflow: -- `bd propose ` - Move issue from planning to upstream -- `bd withdraw ` - Un-propose -- `bd accept ` - Maintainer accepts proposal diff --git a/docs/SETUP.md b/docs/SETUP.md index b0d4ff88d..6c9d22b18 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -1,610 +1,7 @@ -# Setup Command Reference +# Agent and IDE Setup -Last reviewed: 2026-05-08 - -Freshness source: `cmd/bd/setup*.go` and `internal/recipes/`. - -**For:** Setting up beads integration with AI coding tools -**Version:** current CLI behaviour; verify recipe lists against the freshness -source above. - -## Overview - -The `bd setup` command uses a **recipe-based architecture** to configure beads integration with AI coding tools. Recipes define where workflow instructions are writtenβ€”built-in recipes handle popular tools, and you can add custom recipes for any tool. - -### `bd prime` as SSOT - -`bd prime` is the **single source of truth** for operational workflow commands. The beads section in each tool's instruction file provides a pointer to `bd prime` for hook-enabled agents (Claude, Gemini) or the full command reference for AGENTS-first agents (Factory, Mux). Codex uses a Beads skill, generated `AGENTS.md` guidance, and native Codex hooks. - -### Template Profiles - -Each integration uses one of two **profiles** that control how much content is written to tool instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`): - -| Profile | Used By | Content | -|---------|---------|---------| -| `full` | Factory, Codex, Mux, OpenCode | Complete command reference, issue types, priorities, workflow | -| `minimal` | Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) | - -Hook-enabled agents (Claude, Copilot CLI, Gemini) use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Skill-aware agents use `.agents/skills/beads/SKILL.md`, with project `AGENTS.md` or global `$CODEX_HOME/AGENTS.md`/`~/.codex/AGENTS.md` telling Codex when to use the skill. - -**Profile precedence:** If a file already has a `full` profile section and a `minimal` profile tool installs to the same file (e.g., via symlinks), the `full` profile is preserved to avoid information loss. - -### Policy Profiles - -Template profiles control how much text gets installed. Policy profiles control what an agent is authorized to do at handoff: - -| Policy | Default Scope | Commit/Push Guidance | -|--------|---------------|----------------------| -| `conservative` | Standalone projects, unknown projects, and one-off assistance | Use `bd` for task tracking, then report changed files, validation, and proposed commands. Do not commit, push, or run Dolt remote sync without explicit user or orchestrator approval. | -| `minimal` | Hook-first integrations where `bd prime` carries the detailed workflow | Same git authority as conservative; the installed file stays short and points to `bd prime`. | -| `team-maintainer` | Repositories that explicitly delegate session close to agents | Agents may close beads, run quality gates, commit, run `bd dolt push`, and `git push` as part of routine work. Current "do not commit" or "do not push" instructions still override the profile. | - -The generated Beads block and `bd prime` default to conservative git authority. Set the profile explicitly with the `agent.profile` config key or the `BD_AGENT_PROFILE` environment variable (values: `conservative`, `minimal`, `team-maintainer`; env var takes precedence; an unrecognized value falls back to `conservative`): - -```bash -bd config set agent.profile team-maintainer -# or, for a single session/process: -BD_AGENT_PROFILE=team-maintainer bd prime -``` - -`bd prime` layers this explicit knob on top of its existing per-branch git-authority checks (stealth mode, no git remote, ephemeral branch, `no-push`); those hard constraints still take precedence, and `team-maintainer` remains subordinate to any explicit "do not commit"/"do not push" instruction. Beads does not infer team-maintainer authority merely because a remote exists; it must be set via this knob (or, for tools without config access, via top-level project instructions). - -### Built-in Recipes - -| Recipe | Path | Integration Type | -|--------|------|-----------------| -| `cursor` | `.cursor/rules/beads.mdc` | Rules file | -| `windsurf` | `.windsurf/rules/beads.md` | Rules file | -| `cody` | `.cody/rules/beads.md` | Rules file | -| `kilocode` | `.kilocode/rules/beads.md` | Rules file | -| `claude` | `~/.claude/settings.json` + `CLAUDE.md` | SessionStart/PreCompact hooks + minimal section | -| `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | native Copilot plugin hooks + repository instructions | -| `gemini` | `~/.gemini/settings.json` + `GEMINI.md` | SessionStart/PreCompress hooks + minimal section | -| `factory` | `AGENTS.md` | Marked section | -| `codex` | `.agents/skills/beads/SKILL.md` + `AGENTS.md` + `.codex/` | Beads agent skill + generated guidance + native hooks | -| `mux` | `AGENTS.md` | Marked section | -| `aider` | `.aider.conf.yml` + `.aider/` | Multi-file config | - -## Quick Start - -```bash -# List all available recipes -bd setup --list - -# Install integration for your tool -bd setup cursor # Cursor IDE -bd setup windsurf # Windsurf -bd setup kilocode # Kilo Code -bd setup claude # Claude Code -bd setup copilot # GitHub Copilot CLI plugin + instructions -bd setup gemini # Gemini CLI -bd setup factory # Factory.ai Droid -bd setup codex # Beads agent skill + AGENTS.md guidance + native hooks -bd setup mux # Mux -bd setup aider # Aider - -# Verify installation -bd setup cursor --check -bd setup claude --check - -# Print template to stdout (for inspection) -bd setup --print - -# Write template to custom path -bd setup -o .my-editor/rules.md - -# Add a custom recipe -bd setup --add myeditor .myeditor/rules.md -bd setup myeditor # Now you can use it -``` - -## Factory.ai (Droid) - -Factory.ai Droid integration uses the AGENTS.md standard, which is compatible with multiple AI coding assistants. - -### Installation - -```bash -# Create or update AGENTS.md with beads integration -bd setup factory -``` - -### What Gets Installed - -Creates or updates `AGENTS.md` in your project root with: -- Issue tracking workflow instructions -- Quick command reference -- Issue types and priorities -- Dolt remote sync explanation -- Important rules for AI agents - -The beads section is wrapped in HTML comments (``) with metadata for safe updates. The begin marker includes version, profile, and hash metadata (e.g., ``) for freshness detection. Legacy markers without metadata are auto-upgraded on the next install or update. - -### AGENTS.md Standard - -AGENTS.md is an industry-standard format for AI coding agent instructions, supported by: -- **Factory.ai Droid** - Specialized coding agents -- **Cursor** - Also reads AGENTS.md (in addition to .cursor/rules) -- **Aider** - Can be configured to read AGENTS.md -- **Gemini CLI** - Google's command-line AI assistant -- **Jules** - Google's coding assistant -- **Codex** - OpenAI's code generation model -- **Zed** - AI-enhanced editor -- And many more emerging tools - -Using AGENTS.md means one configuration file works across your entire AI tool ecosystem. - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check if beads section exists and is current (reports `missing`, `stale`, or `current`) | -| `--remove` | Remove beads section from AGENTS.md | - -### Examples - -```bash -# Check if beads section is in AGENTS.md -bd setup factory --check -# Output: βœ“ Factory.ai integration installed: AGENTS.md -# Beads section found in AGENTS.md - -# Remove beads section -bd setup factory --remove -``` - -### How It Works - -Factory Droid and other AGENTS.md-compatible tools automatically read `AGENTS.md` from: -1. Current working directory (`./AGENTS.md`) -2. Parent directories up to repo root -3. Personal override (`~/.factory/AGENTS.md`) - -The beads section teaches AI agents: -- To use `bd ready` for finding work -- To use `bd create` for tracking new issues -- To treat commit, push, and Dolt remote sync as policy-controlled handoff actions -- The complete workflow pattern and best practices - -### Updating Existing AGENTS.md - -If you already have an AGENTS.md file with other project instructions: -- `bd setup factory` will **append** the beads section -- Re-running it will **update** the existing beads section (idempotent) -- The markers (``) ensure safe updates - -### When to Use This vs Other Integrations - -**Use Factory integration when:** -- βœ… You use Factory.ai Droid -- βœ… You want one config file for multiple AI tools -- βœ… You prefer the AGENTS.md standard -- βœ… Your team uses multiple AI coding assistants - -**Use other integrations when:** -- βœ… You only use Claude Code β†’ `bd setup claude` (hooks are more dynamic) -- βœ… You need tool-specific features (like Claude's stealth mode) - -You can use multiple integrations simultaneously - they complement each other! - -## Codex CLI - -Codex reads project instructions from `AGENTS.md` in the current working directory or project root, and global instructions from `$CODEX_HOME/AGENTS.md` when `CODEX_HOME` is set, otherwise `~/.codex/AGENTS.md`. The Codex setup path installs the generic `beads` agent skill, writes managed Codex guidance, enables native hooks, and installs a fallback hooks file when the Beads Codex plugin is not managing hooks. - -### Installation - -```bash -bd setup codex # Project Beads skill + AGENTS.md guidance + native hooks -bd setup codex --global # Global Beads skill + guidance + native hooks -``` - -### What Gets Installed - -**Project install** (`bd setup codex`): -- Creates or updates `.agents/skills/beads/SKILL.md` -- Creates or updates `.agents/skills/beads/agents/openai.yaml` -- Creates or updates project `AGENTS.md` with a marked section generated by `bd setup codex` -- Creates or updates `.codex/config.toml` with native hooks enabled -- Creates or updates `.codex/hooks.json` unless hooks are plugin-managed - -**Global install** (`bd setup codex --global`): -- Creates or updates `~/.agents/skills/beads/SKILL.md` -- Creates or updates `~/.agents/skills/beads/agents/openai.yaml` -- Creates or updates `$CODEX_HOME/AGENTS.md` when `CODEX_HOME` is set, otherwise `~/.codex/AGENTS.md`, with a marked section generated by `bd setup codex --global` -- Creates or updates global Codex hook configuration under `$CODEX_HOME` when set, otherwise `~/.codex` - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check the Beads agent skill, managed Codex `AGENTS.md` guidance, and native hooks | -| `--remove` | Remove the Beads agent skill, managed Codex `AGENTS.md` guidance, and native hooks | -| `--global` | Install/check/remove the global skill, global Codex guidance, and native hooks | - -### Notes - -- Restart Codex if it's already running to pick up the new instructions. -- The plugin package under `plugins/beads/` is separate from `bd setup codex`. The setup command writes a small setup-only skill and managed guidance into the target repository or user-level `.agents` directory. -- `bd init` runs project `bd setup codex` automatically unless `--skip-agents` or `--stealth` is used. -- In worktree/shared/`BEADS_DIR` setups, use `bd where` to confirm the resolved workspace; the integration does not require a local `./.beads`. -- `bd setup codex` uses its own marker pair (`BEGIN/END BEADS CODEX SETUP`), distinct from the `BEGIN/END BEADS INTEGRATION` markers used by `bd setup factory` and `bd setup mux`. Running both `bd setup codex` and `bd setup factory`/`mux` against the same `AGENTS.md` will leave two managed sections side by side; each `bd setup … --check` only inspects its own section, and `bd setup … --remove` only removes its own section. - -## Mux - -Mux reads layered instruction files, including workspace `AGENTS.md`. Adding the beads section is enough to get Mux and beads working together. - -### Installation - -```bash -bd setup mux # Root AGENTS.md -bd setup mux --project # Root AGENTS.md + .mux/AGENTS.md -bd setup mux --global # Root AGENTS.md + ~/.mux/AGENTS.md -``` - -### What Gets Installed - -Creates or updates `AGENTS.md` with the beads integration section (same markers as Factory.ai and Codex). - -### Notes - -- Mux instruction file behavior is documented at [https://mux.coder.com/AGENTS.md](https://mux.coder.com/AGENTS.md). -- Restart the workspace session if Mux is already running. - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check root integration (and with layer flags, also check those layers) | -| `--remove` | Remove root integration (and with layer flags, also remove those layers) | -| `--project` | Install/check/remove workspace-layer instructions in `.mux/AGENTS.md` | -| `--global` | Install/check/remove global-layer instructions in `~/.mux/AGENTS.md` | - -## Claude Code - -Claude Code integration uses hooks to automatically inject beads workflow context at session start and before context compaction. - -### Installation - -```bash -# Global installation (recommended) -bd setup claude - -# Project-only installation -bd setup claude --project - -# With stealth mode (flush only, no git operations) -bd setup claude --stealth -``` - -### What Gets Installed - -**Global installation** (`~/.claude/settings.json`): -- `SessionStart` hook: Runs `bd prime --hook-json` when a session starts, resumes, clears, or restarts after compaction - -**Project installation** (`.claude/settings.local.json`): -- Same hooks, but only active for this project - -**Instruction file** (`CLAUDE.md` in project root): -- Minimal-profile beads section pointing to `bd prime` -- Managed with hash/version markers for safe updates and `--check` freshness detection - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check both hooks and the managed `CLAUDE.md` beads section | -| `--remove` | Remove beads hooks and managed `CLAUDE.md` beads section | -| `--project` | Install for this project only (not globally) | -| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) | - -### Examples - -```bash -# Check hooks + CLAUDE.md beads section -bd setup claude --check -# Output: βœ“ Global hooks installed: /Users/you/.claude/settings.json -# βœ“ Claude Code integration installed: /path/to/CLAUDE.md (current) - -# Remove hooks -bd setup claude --remove - -# Install project-specific hooks with stealth mode -bd setup claude --project --stealth -``` - -### How It Works - -The hook calls `bd prime --hook-json` which: -1. Outputs workflow context wrapped in the SessionStart JSON envelope Claude Code expects -2. Prints persistent memories near the top so hook-output previews do not hide them -3. Starts with a truncation warning telling agents to read the full persisted hook output when the host caps previews -4. Ensures Claude always knows how to use beads -5. Follows resolved workspace semantics, so `bd where` is the right diagnostic check when local `./.beads` is absent - -For low-token hooks that only need durable project facts, use `bd prime --memories-only`. - -This is more context-efficient than MCP tools (~1-2k tokens vs 10-50k for MCP schemas). - -## Gemini CLI - -Gemini CLI integration uses a SessionStart hook to automatically inject beads workflow context when a session opens. - -### Installation - -```bash -# Global installation (recommended) -bd setup gemini - -# Project-only installation -bd setup gemini --project - -# With stealth mode (flush only, no git operations) -bd setup gemini --stealth -``` - -### What Gets Installed - -**Global installation** (`~/.gemini/settings.json`): -- `SessionStart` hook: Runs `bd prime --hook-json` when a new session starts, wrapped in the JSON envelope Gemini's hook contract requires - -**Project installation** (`.gemini/settings.json`): -- Same hooks, but only active for this project - -**Instruction file** (`GEMINI.md` in project root): -- Minimal-profile beads section pointing to `bd prime` -- Managed with hash/version markers for safe updates and `--check` freshness detection - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check both hooks and the managed `GEMINI.md` beads section | -| `--remove` | Remove beads hooks and managed `GEMINI.md` beads section | -| `--project` | Install for this project only (not globally) | -| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) | - -### Examples - -```bash -# Check hooks + GEMINI.md beads section -bd setup gemini --check -# Output: βœ“ Global hooks installed: /Users/you/.gemini/settings.json -# βœ“ Gemini CLI integration installed: /path/to/GEMINI.md (current) - -# Remove hooks -bd setup gemini --remove - -# Install project-specific hooks with stealth mode -bd setup gemini --project --stealth -``` - -### How It Works - -The hooks call `bd prime` which: -1. Outputs workflow context for Gemini to read -2. Prints persistent memories near the top so hook-output previews do not hide them -3. Starts with a truncation warning telling agents to read the full persisted hook output when the host caps previews -4. Ensures Gemini always knows how to use beads - -For low-token hooks that only need durable project facts, use `bd prime --memories-only`. - -This works similarly to Claude Code integration, using Gemini CLI's hook system (SessionStart event). Unlike Claude Code, Gemini requires hook stdout to be valid JSON β€” `bd prime --hook-json` wraps the markdown in the required envelope. - -## Cursor IDE - -Cursor integration creates a rules file that provides beads workflow context to the AI. - -### Installation - -```bash -bd setup cursor -``` - -### What Gets Installed - -Creates `.cursor/rules/beads.mdc` with: -- Core workflow rules (track work in bd, not markdown TODOs) -- Quick command reference -- Workflow pattern (ready β†’ claim β†’ work β†’ close β†’ sync) -- Context loading instructions - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check if integration is installed | -| `--remove` | Remove beads rules file | - -### Examples - -```bash -# Check if rules are installed -bd setup cursor --check -# Output: βœ“ Cursor integration installed: .cursor/rules/beads.mdc - -# Remove rules -bd setup cursor --remove -``` - -### How It Works - -Cursor reads `.cursor/rules/*.mdc` files and includes them in the AI's context. The beads rules file teaches the AI: -- To use `bd ready` for finding work -- To use `bd create` for tracking new issues -- To treat commit, push, and Dolt remote sync as policy-controlled handoff actions -- The basic workflow pattern - -## Aider - -Aider integration creates configuration files that teach the AI about beads, while respecting Aider's human-in-the-loop design. - -### Installation - -```bash -bd setup aider -``` - -### What Gets Installed - -| File | Purpose | -|------|---------| -| `.aider.conf.yml` | Points Aider to read the instructions file | -| `.aider/BEADS.md` | Workflow instructions for the AI | -| `.aider/README.md` | Quick reference for humans | - -### Flags - -| Flag | Description | -|------|-------------| -| `--check` | Check if integration is installed | -| `--remove` | Remove beads configuration | - -### Examples - -```bash -# Check if config is installed -bd setup aider --check -# Output: βœ“ Aider integration installed: .aider.conf.yml - -# Remove configuration -bd setup aider --remove -``` - -### How It Works - -Unlike Claude Code, Aider requires explicit command execution. The AI will **suggest** bd commands, which the user runs via `/run`: - -``` -You: What issues are ready to work on? - -Aider: Let me check. Run: -/run bd ready - -You: [runs the command] - -Aider: Great! To claim bd-42, run: -/run bd update bd-42 --claim -``` - -This respects Aider's philosophy of keeping humans in control while still leveraging beads for issue tracking. - -## Comparison - -| Feature | Factory.ai | Codex | Mux | Claude Code | Gemini CLI | Cursor | Aider | -|---------|-----------|-------|-----|-------------|------------|--------|-------| -| Command execution | Automatic | Automatic | Automatic | Automatic | Automatic | Automatic | Manual (/run) | -| Context injection | AGENTS.md | Skill + AGENTS.md | AGENTS.md | Hooks + CLAUDE.md | Hooks + GEMINI.md | Rules file | Config file | -| Global install | No (per-project) | No (per-project) | No (per-project) | Yes | Yes | No (per-project) | No (per-project) | -| Stealth mode | N/A | N/A | N/A | Yes | Yes | N/A | N/A | -| Standard format | Yes (AGENTS.md) | Yes (AGENTS.md) | Yes (AGENTS.md) | No (proprietary) | No (proprietary) | No (proprietary) | No (proprietary) | -| Multi-tool compatible | Yes | Yes | Yes | No | No | No | No | - -## Best Practices - -1. **Start with Factory integration** - Creates AGENTS.md which works across multiple AI tools: - ```bash - bd setup factory - ``` - -2. **Add tool-specific integrations as needed** - Claude hooks, Cursor rules, or Aider config for tool-specific features - -3. **Install globally for Claude Code or Gemini CLI** - You'll get beads context in every project automatically - -4. **Use stealth mode in CI/CD** - `bd setup claude --stealth` or `bd setup gemini --stealth` avoids git operations that might fail in automated environments - -5. **Commit instruction files to git** - This ensures all team members and AI tools get the same instructions (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, as applicable) - -6. **Run `bd doctor` after setup** - Verifies the integration is working: - ```bash - bd doctor | grep -iE "claude|gemini" - # Claude Integration: Hooks installed (CLI mode) - # Gemini CLI Integration: Hooks installed - ``` - -## Troubleshooting - -### "Hooks not working" - -1. Restart your AI tool after installation -2. Verify with `bd setup --check` -3. Check `bd doctor` output for integration status - -### "Context not appearing" - -For Claude Code, ensure `bd prime` works standalone: -```bash -bd prime -``` - -If this fails, fix the underlying beads issue first. - -### "Want to switch from global to project hooks" - -```bash -# Remove global hooks -bd setup claude --remove - -# Install project hooks -bd setup claude --project -``` - -## Custom Recipes - -You can add custom recipes for editors/tools not included in the built-in list. - -### Adding a Custom Recipe - -```bash -# Add a recipe that writes to a specific path -bd setup --add myeditor .myeditor/rules.md - -# Install it -bd setup myeditor - -# Check it -bd setup myeditor --check - -# Remove it -bd setup myeditor --remove -``` - -### User Recipes File - -Custom recipes are stored in `.beads/recipes.toml`: - -```toml -[recipes.myeditor] -name = "myeditor" -path = ".myeditor/rules.md" -type = "file" -``` - -### Using Arbitrary Paths - -For one-off installs without saving a recipe: - -```bash -# Write template to any path -bd setup -o .my-custom-location/beads.md - -# Inspect the template first -bd setup --print -``` - -### Recipe Types - -| Type | Description | Example | -|------|-------------|---------| -| `file` | Write template to a single file | cursor, windsurf, cody, kilocode | -| `hooks` | Modify JSON settings to add hooks | claude, gemini | -| `section` | Inject marked section into existing file | factory | -| `multifile` | Write multiple files | aider | - -Custom recipes added via `--add` are always type `file`. - -## Related Documentation - -- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Design decisions for Claude Code integration -- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider workflow guide -- [QUICKSTART.md](QUICKSTART.md) - Getting started with beads -- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Full command reference +This guide moved to [getting-started/ide-setup.md](getting-started/ide-setup.md) +as part of the Mintlify docs site under `docs/`. This pointer stays because +released `bd` binaries print `docs/SETUP.md#policy-profiles` (in `bd prime` +help); that section is now at +[getting-started/ide-setup.md](getting-started/ide-setup.md#policy-profiles). diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md deleted file mode 100644 index 39cee3567..000000000 --- a/docs/TROUBLESHOOTING.md +++ /dev/null @@ -1,1092 +0,0 @@ -# Troubleshooting bd - -Common issues and solutions for bd users. - -## Table of Contents - -- [Debug Environment Variables](#debug-environment-variables) -- [Installation Issues](#installation-issues) -- [Antivirus False Positives](#antivirus-false-positives) -- [Database Issues](#database-issues) - - [Circuit breaker: "server appears down, failing fast"](#circuit-breaker-server-appears-down-failing-fast) - - [Connection failures after upgrading from pre-Dolt versions](#connection-failures-after-upgrading-from-pre-dolt-versions) -- [Git and Sync Issues](#git-and-sync-issues) -- [Ready Work and Dependencies](#ready-work-and-dependencies) -- [Performance Issues](#performance-issues) -- [Agent-Specific Issues](#agent-specific-issues) -- [Platform-Specific Issues](#platform-specific-issues) - -## Debug Environment Variables - -bd supports several environment variables for debugging specific subsystems. Enable these when troubleshooting issues or when requested by maintainers. - -### Available Debug Variables - -| Variable | Purpose | Output Location | Usage | -|----------|---------|----------------|-------| -| `BD_DEBUG` | General debug logging | stderr | Set to any value to enable | -| `BD_DEBUG_RPC` | RPC communication between CLI and Dolt server | stderr | Set to `1` or `true` | -| `BD_DEBUG_SYNC` | Sync and import timestamp protection | stderr | Set to any value to enable | -| `BD_DEBUG_ROUTING` | Issue routing and multi-repo resolution | stderr | Set to any value to enable | -| `BD_DEBUG_FRESHNESS` | Database file replacement detection | server logs | Set to any value to enable | - -### Usage Examples - -**General debugging:** -```bash -# Enable all general debug logging -export BD_DEBUG=1 -bd ready -``` - -**RPC communication issues:** -```bash -# Debug Dolt server communication -export BD_DEBUG_RPC=1 -bd list - -# Example output: -# [RPC DEBUG] Connecting to Dolt server -# [RPC DEBUG] Sent request: list (correlation_id=abc123) -# [RPC DEBUG] Received response: 200 OK -``` - -**Sync conflicts:** -```bash -# Debug timestamp protection during sync -export BD_DEBUG_SYNC=1 -bd dolt push - -# Example output: -# [debug] Protected bd-123: local=2024-01-20T10:00:00Z >= incoming=2024-01-20T09:55:00Z -``` - -**Routing issues:** -```bash -# Debug issue routing in multi-repo setups -export BD_DEBUG_ROUTING=1 -bd create "Test issue" --rig=planning - -# Example output: -# [routing] Rig "planning" -> prefix plan, path /path/to/planning-repo (townRoot=/path/to/town) -# [routing] ID plan-123 matched prefix plan -> /path/to/planning-repo/beads -``` - -**Database reconnection issues:** -```bash -# Debug database file replacement detection -export BD_DEBUG_FRESHNESS=1 -bd dolt start - -# Example output: -# [freshness] FreshnessChecker: inode changed 27548143 -> 7945906 -# [freshness] FreshnessChecker: triggering reconnection -# [freshness] Database file replaced, reconnection triggered - -# Or check server logs -tail -f .beads/dolt/sql-server.log | grep freshness -``` - -**Multiple debug flags:** -```bash -# Enable multiple subsystems -export BD_DEBUG=1 -export BD_DEBUG_RPC=1 -export BD_DEBUG_FRESHNESS=1 -bd dolt start -``` - -### Tips - -- **Disable after debugging**: Debug logging can be verbose. Disable by unsetting the variable: - ```bash - unset BD_DEBUG - unset BD_DEBUG_RPC - # etc. - ``` - -- **Capture debug output**: Redirect stderr to a file for analysis: - ```bash - BD_DEBUG=1 bd dolt push 2> debug.log - ``` - -- **Server logs**: `BD_DEBUG_FRESHNESS` output goes to server logs, not stderr: - ```bash - # View Dolt server logs - tail -f .beads/dolt/sql-server.log - ``` - -- **When filing bug reports**: Include relevant debug output to help maintainers diagnose issues faster. - -### Related Documentation - -- [ROUTING.md](ROUTING.md) - Multi-repo routing configuration - -## Installation Issues - -### `bd: command not found` - -bd is not in your PATH. Either: - -```bash -# Check if installed -go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd - -# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) -export PATH="$PATH:$(go env GOPATH)/bin" - -# Or reinstall with the recommended installer -curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -``` - -### Wrong version of bd running / Multiple bd binaries in PATH - -If `bd version` shows an unexpected version (e.g., older than what you just installed), you likely have multiple `bd` binaries in your PATH. - -**Diagnosis:** -```bash -# Check all bd binaries in PATH -which -a bd - -# Example output showing conflict: -# /Users/you/go/bin/bd <- From go install (older) -# /opt/homebrew/bin/bd <- From Homebrew (newer) -``` - -**Solution:** -```bash -# Remove old go install version -rm ~/go/bin/bd - -# Or remove mise-managed Go installs -rm ~/.local/share/mise/installs/go/*/bin/bd - -# Verify you're using the correct version -which bd # Should show /opt/homebrew/bin/bd or your package manager path -bd version # Should show the expected version -``` - -**Why this happens:** If you previously installed bd via `go install`, the binary was placed in `~/go/bin/`. When you later install via Homebrew or another package manager, the old `~/go/bin/bd` may appear earlier in your PATH, causing the wrong version to run. - -**Recommendation:** Choose one installation method (Homebrew recommended) and stick with it. Avoid mixing `go install` with package managers. - -### `zsh: killed bd` or crashes on macOS - -Some users report crashes when running `bd init` or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues. - -**Workaround:** -```bash -# Install an embedded-capable build -CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest - -# Or if building from source -git clone https://github.com/gastownhall/beads -cd beads -CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd -sudo mv bd /usr/local/bin/ -``` - -If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please [file an issue](https://github.com/gastownhall/beads/issues). - -## Antivirus False Positives - -### Antivirus software flags bd as malware - -**Symptom**: Kaspersky, Windows Defender, or other antivirus software detects `bd` or `bd.exe` as a trojan or malicious software and removes it. - -**Common detections**: -- Kaspersky: `PDM:Trojan.Win32.Generic` -- Windows Defender: Various generic trojan detections - -**Cause**: This is a **false positive**. Go binaries are commonly flagged by antivirus heuristics because some malware is written in Go. This is a known industry-wide issue affecting many legitimate Go projects. - -**Solutions**: - -1. **Verify file integrity first**: - ```bash - # Windows PowerShell - Get-FileHash bd.exe -Algorithm SHA256 - - # macOS/Linux - shasum -a 256 bd - ``` - Compare with checksums from the [GitHub release page](https://github.com/gastownhall/beads/releases) - -2. **Add bd to antivirus exclusions only after verification**: - - Add the bd installation directory to your antivirus exclusion list - - Keep antivirus enabled for everything else - -3. **Report the false positive**: - - Help improve detection by reporting to your antivirus vendor - - Most vendors have false positive submission forms - -**Detailed guide**: See [docs/ANTIVIRUS.md](ANTIVIRUS.md) for complete instructions including: -- How to add exclusions for specific antivirus software -- How to report false positives to vendors -- Why Go binaries trigger these detections -- Future plans for code signing - -## Database Issues - -### Port conflicts with multiple projects - -**Symptom:** Running `bd init` or `bd` commands in a second project fails or connects to the wrong database. Multiple `dolt sql-server` processes are running. - -**Cause:** By default, each beads project starts its own Dolt server. On machines with multiple projects, this can cause port conflicts or resource waste. - -**Fix:** Enable shared server mode so all projects use a single Dolt server: - -```bash -# Option 1: Machine-wide (add to ~/.bashrc or ~/.zshrc) -export BEADS_DOLT_SHARED_SERVER=1 - -# Option 2: Per-project -cd ~/project1 && bd dolt set shared-server true -cd ~/project2 && bd dolt set shared-server true -``` - -After enabling, existing projects may need `bd init --force -q` to create their database on the shared server. - -**Verify:** `bd dolt status` from any project should show the same PID, port 3308, and `~/.beads/shared-server/` as the data directory. - -### `bd` shows 0 issues but the database has data - -**Symptom:** All `bd` commands return empty results. `bd list` shows nothing. - -**Cause:** Your `bd` may be connecting to a different Dolt server or database than expected. Before the version including the shadow DB fix (see [CHANGELOG](../CHANGELOG.md)), `bd` unconditionally ran `CREATE DATABASE IF NOT EXISTS` on every connection, which could create an empty shadow database on the wrong server. - -**Diagnosis:** - -```bash -# Check what server bd is connecting to -cat .beads/metadata.json | grep -E "dolt_mode|dolt_server" - -# Check if the database exists on the expected server -dolt sql -q "SHOW DATABASES" --host 127.0.0.1 --port 3307 - -# Query your data directly to confirm it exists -cd /path/to/your/dolt/data/beads_myproject -dolt sql -q "SELECT COUNT(*) FROM issues" - -# Run diagnostics -bd doctor --server -``` - -**Fix:** - -1. Upgrade `bd` to a version including the shadow DB fix (see [CHANGELOG](../CHANGELOG.md)) -2. Ensure your Dolt server is running from the correct data directory -3. Verify `metadata.json` points to the right server and port -4. If a stale `.beads/dolt/` directory exists alongside server mode, remove it: - ```bash - rm -rf .beads/dolt/ - ``` - -### Configured server unreachable (auto-start disabled) - -**Symptom (after shadow DB fix):** `bd` returns "database not found on Dolt server" when the configured server is down. - -**Cause:** When `metadata.json` has an explicit `dolt_server_port`, auto-start is intentionally disabled. Starting a different server would create a shadow database. - -**Fix:** - -```bash -# Start your configured Dolt server -bd dolt start - -# Or start manually with the correct data directory -dolt sql-server --host 127.0.0.1 --port 3307 --data-dir /path/to/your/dolt/data -``` - -If you want auto-start behavior, remove `dolt_server_port` from `.beads/metadata.json`. - -### Dolt journal corruption after restart - -**Symptom:** After a system restart, `bd` reports that the Dolt server started -but is not accepting connections, and `.beads/dolt-server.log` contains: - -```text -possible data loss detected in journal file at offset ...: corrupted journal -``` - -**Cause:** Dolt detected damaged journal blocks after an unclean shutdown. This -is not the same as a stale PID, stale port, or stale lock file. `bd` will not -run Dolt's data-loss repair mode automatically. - -**Safe recovery when your remote is current:** - -```bash -mv .beads/dolt .beads/dolt.corrupt.$(date +%Y%m%dT%H%M%S) -bd bootstrap --dry-run -bd bootstrap --yes -bd stats -``` - -If the remote may be stale, keep the corrupt directory for forensics and inspect -it with `dolt fsck` before considering `dolt fsck --revive-journal-with-data-loss`. -Only use the revive path after reviewing Dolt's data-loss warning. - -### `database is locked` - -Another bd process is accessing the database. Solutions: - -```bash -# Find and kill hanging processes -ps aux | grep bd -kill - -# WARNING: Do NOT remove files inside .dolt/ directories (including noms/LOCK). -# These are Dolt-internal files β€” removing them WILL cause unrecoverable -# data corruption. Dolt manages these files itself. - -# For server mode: restart the Dolt server -# (server mode handles concurrent access natively) -``` - -**Note**: For high-concurrency scenarios (multiple agents), use Dolt server mode (`bd dolt set mode server`) which handles concurrent access natively via `dolt sql-server`. - -### `bd init` fails with "directory not empty" - -`.beads/` already exists. Options: - -```bash -# Use existing database -bd list # Should work if already initialized - -# Or remove and reinitialize (DESTROYS DATA!) -rm -rf .beads/ -bd init -``` - -### `failed to import: issue already exists` - -You're trying to bootstrap a database with issues that conflict with existing ones. Options: - -```bash -# Clear database and re-initialize from an export -rm -rf .beads/dolt -bd init --from-jsonl -``` - -### Import fails with missing parent errors - -If you see errors like `parent issue bd-abc does not exist` when bootstrapping from JSONL or pulling hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), this means the parent issue was deleted but children still reference it. - -**Quick fix using resurrection:** - -```bash -# Set orphan handling to auto-resurrect deleted parents -bd config set import.orphan_handling "resurrect" - -# Then pull or re-initialize -bd dolt pull -``` - -**What resurrection does:** - -1. Searches the import data for the missing parent issue -2. Recreates it as a tombstone (Status=Closed, Priority=4) -3. Preserves the parent's original title and description -4. Maintains referential integrity for hierarchical children -5. Also resurrects dependencies on best-effort basis - -**Other handling modes:** - -```bash -# Allow orphans (default) - import without validation -bd config set import.orphan_handling "allow" - -# Skip orphans - partial import with warnings -bd config set import.orphan_handling "skip" - -# Strict - fail fast on missing parents -bd config set import.orphan_handling "strict" -``` - -**When this happens:** - -- Parent issue was deleted using `bd delete` -- Branch merge where one side deleted the parent -- Manual editing that removed parent entries -- Database corruption or incomplete import - -**Prevention:** - -- Use `bd delete --cascade` to also delete children -- Check for orphans before cleanup: `bd list --id bd-abc.*` -- Review impact before deleting epic/parent issues - -See [CONFIG.md](CONFIG.md#example-import-orphan-handling) for complete configuration documentation. - -### Old data returns after reset - -**Symptom:** After running `bd admin reset --force` and `bd init`, old issues reappear. - -**Cause:** `bd admin reset --force` only removes **local** beads data. Old data can return from: - -1. **Dolt remotes** - If you have configured Dolt remotes, old data may exist there -2. **Remote sync branch** - If you configured a sync branch, old data may exist on the remote -3. **Other machines** - Other clones may push old data after you reset - -**Solution for complete clean slate:** - -```bash -# 1. Reset local beads -bd admin reset --force - -# 2. Delete remote sync branch (if configured) -# Check your sync branch name first: -bd config get sync.branch -# Then delete it from remote: -git push origin --delete -# Common names: beads-sync, beads-metadata - -# 3. Re-initialize -bd init -``` - -**Less destructive alternatives:** - -```bash -# Option A: Just delete the sync branch and reinit -bd admin reset --force -git push origin --delete beads-sync # or your sync branch name -bd init - -# Option B: Start fresh without sync branch -bd admin reset --force -bd init -bd config set sync.branch "" # Disable sync branch feature -``` - -**Note:** The `--hard` and `--skip-init` flags mentioned in [GH#479](https://github.com/gastownhall/beads/issues/479) were never implemented. Use the workarounds above for a complete reset. - -**Related:** [GH#922](https://github.com/gastownhall/beads/issues/922) - -### Database corruption - -**Important**: Distinguish between **logical consistency issues** (ID collisions, wrong prefixes) and **physical database corruption**. - -For **physical database corruption** (disk failures, power loss, filesystem errors): - -```bash -# If corrupted, rebuild from a Dolt remote or from a backup snapshot -mv .beads/dolt .beads/dolt.backup -bd init -bd dolt pull # Pull from Dolt remote if configured -# Or restore from a backup: -# bd backup restore [path] --force -``` - -For **logical consistency issues** (ID collisions from branch merges, parallel workers): - -```bash -# This is NOT corruption - use Dolt merge or bd doctor --fix -bd doctor --fix -``` - -See [FAQ](FAQ.md#whats-the-difference-between-database-corruption-and-id-collisions) for the distinction. - -### Multiple databases detected warning - -If you see a warning about multiple `.beads` databases in the directory hierarchy: - -``` -╔══════════════════════════════════════════════════════════════════════════╗ -β•‘ WARNING: 2 beads databases detected in directory hierarchy β•‘ -╠══════════════════════════════════════════════════════════════════════════╣ -β•‘ Multiple databases can cause confusion and database pollution. β•‘ -β•‘ β•‘ -β•‘ β–Ά /path/to/project/.beads (15 issues) β•‘ -β•‘ /path/to/parent/.beads (32 issues) β•‘ -β•‘ β•‘ -β•‘ Currently using the closest database (β–Ά). This is usually correct. β•‘ -β•‘ β•‘ -β•‘ RECOMMENDED: Consolidate or remove unused databases to avoid confusion. β•‘ -β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• -``` - -This means bd found multiple `.beads` directories in your directory hierarchy. The `β–Ά` marker shows which database is actively being used (usually the closest one to your current directory). - -**Why this matters:** -- Can cause confusion about which database contains your work -- Easy to accidentally work in the wrong database -- May lead to duplicate tracking of the same work - -**Solutions:** - -1. **If you have nested projects** (intentional): - - This is fine! bd is designed to support this - - Just be aware which database you're using - - Set `BEADS_DIR` environment variable to point to your `.beads` directory if you want to override the default selection - - Or use `BEADS_DB` (deprecated) to point directly to the database file - -2. **If you have accidental duplicates** (unintentional): - - Decide which database to keep - - Export issues from the unwanted database: `cd && bd export -o issue-export.jsonl` - - Remove the unwanted `.beads` directory: `rm -rf /.beads` - - Optionally import issues into the main database if needed - -3. **Override database selection**: - ```bash - # Temporarily use specific .beads directory (recommended) - BEADS_DIR=/path/to/.beads bd list - - # Or add to shell config for permanent override - export BEADS_DIR=/path/to/.beads - - # Legacy method (deprecated, points to database file directly) - BEADS_DB=/path/to/.beads/issues.db bd list - export BEADS_DB=/path/to/.beads/issues.db - ``` - -**Note**: The warning only appears when bd detects multiple databases. If you see this consistently and want to suppress it, you're using the correct database (marked with `β–Ά`). - -### Circuit breaker: "server appears down, failing fast" - -**Symptom:** Every `bd` command fails with `dolt circuit breaker is open: server appears down, failing fast (cooldown 30s)`. This persists across repeated invocations. - -**Cause:** The circuit breaker tripped after repeated connection failures. Its state is stored in a file at `/tmp/beads-dolt-circuit--.json` (keyed on host:port) and shared across all `bd` processes. Once tripped, all commands to that specific host:port are rejected until a successful probe resets it. - -**Note:** `bd dolt status` checks the server's PID file, not whether the server is actually accepting connections. A "running" status does not guarantee the server is reachable on the expected port. - -**Diagnosis:** - -```bash -# Check circuit breaker state -cat /tmp/beads-dolt-circuit-*.json - -# Check if the Dolt server is actually listening -lsof -i : - -# Compare configured port with what's actually running -cat .beads/metadata.json | grep port -``` - -**Fix:** - -```bash -rm /tmp/beads-dolt-circuit-*.json -bd dolt stop -bd dolt start -bd list -``` - -**Note (macOS):** On macOS, `/tmp` is a symlink to `/private/tmp`. The circuit breaker state file may persist across reboots since `/private/tmp` is not always cleared on restart. - -### Connection failures after upgrading from pre-Dolt versions - -**Symptom:** After upgrading from v0.49 or earlier to v0.58+, `bd` commands fail with connection errors or the circuit breaker trips on first run. - -**Cause:** Pre-Dolt versions used SQLite for storage. The Dolt backend requires a running Dolt server. On first run after upgrading, the server may not be configured or started yet. - -**Fix:** - -1. If you have existing JSONL data from before v0.50, migrate it using the provided script: - ```bash - scripts/migrate-jsonl-to-dolt.sh - ``` -2. Start the Dolt server: - ```bash - bd dolt start - ``` -3. If the circuit breaker tripped during failed connection attempts, clear the state file (see [Circuit breaker: "server appears down, failing fast"](#circuit-breaker-server-appears-down-failing-fast) above). -4. Verify everything is working: - ```bash - bd list - ``` - -## Git and Sync Issues - -### Merge conflicts - -Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects the conflict and allows resolution via SQL: - -```bash -# Check for conflicts after a Dolt pull -bd dolt pull - -# Resolve conflicts if any -bd vc conflicts -``` - -**With hash-based IDs (v0.20.1+), ID collisions don't occur.** Different issues get different hash IDs. - -See [ADVANCED.md#handling-git-merge-conflicts](ADVANCED.md#handling-git-merge-conflicts) for details. - -### Hook timeout kills chained pre-commit hooks - -**Symptom:** After `bd hooks install`, chained pre-commit hooks (eslint, prettier, ruff, etc.) stop running. You see: `beads: hook 'pre-commit' timed out after 300s -- continuing without beads`. - -**Cause:** The beads hook shim wraps `bd hooks run` with an OS-level `timeout`. Since `bd hooks run` chains to your original hook (`.git/hooks/pre-commit.old`) internally, the timeout covers both beads' own work and your entire hook pipeline. - -**Fix:** Increase the timeout via the `BEADS_HOOK_TIMEOUT` environment variable: - -```bash -# Add to ~/.bashrc or ~/.zshrc -export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds) -``` - -The default timeout is 300 seconds (5 minutes). For repos with very heavy pre-commit pipelines, you may need to increase this further. - -### Permission denied on git hooks - -Git hooks need execute permissions: - -```bash -chmod +x .git/hooks/pre-commit -chmod +x .git/hooks/post-merge -chmod +x .git/hooks/post-checkout -``` - -### Corrupted symlinked `CLAUDE.md` - -**Symptom:** Git reports `CLAUDE.md` as a symlink entry (`mode 120000`), but -the indexed blob contains multi-line Markdown instead of a one-line symlink -target. On macOS this can make clones or checkouts fail because symlink targets -cannot contain newline-separated Markdown content. - -This affects repositories that were already corrupted by older setup behavior. -The setup bug has been fixed ([#4192](https://github.com/gastownhall/beads/pull/4192)); -the recipe below repairs an existing bad Git index entry. - -**Confirm the bad entry:** - -```bash -git ls-files -s CLAUDE.md -git cat-file -p :CLAUDE.md | sed -n '1,5p' -``` - -If `git ls-files -s` starts with `120000` and `git cat-file` prints Markdown, -convert the existing blob to a regular tracked file without changing its -content: - -```bash -sha=$(git rev-parse :CLAUDE.md) -git update-index --cacheinfo 100644,$sha,CLAUDE.md -git checkout-index -f -- CLAUDE.md - -# Verify that the index now records a normal file. -git ls-files -s CLAUDE.md -git diff -- CLAUDE.md -``` - -Commit the mode repair after review. The first column from `git ls-files -s` -should now be `100644`. - -### "Branch already checked out" when switching branches - -**Symptom:** -```bash -$ git checkout main -fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync' -``` - -**Cause:** Beads previously created git worktrees internally for a sync-branch feature (configured via `bd config set sync.branch`). These worktrees lock the branches they're checked out to. This feature has been removed; Dolt now stores data under `refs/dolt/data`, separate from standard Git refs. - -**Solution:** -```bash -# Remove beads-created worktrees -rm -rf .git/beads-worktrees -rm -rf .git/worktrees/beads-* -git worktree prune - -# Now you can checkout the branch -git checkout main -``` - -**Permanent fix (disable sync-branch):** -```bash -bd config set sync.branch "" -``` - -See [WORKTREES.md#legacy-cleanup](WORKTREES.md#legacy-cleanup) for details. - -### Unexpected worktree directories in .git/ - -**Symptom:** You notice `.git/beads-worktrees/` or `.git/worktrees/beads-*` directories you didn't create. - -**Explanation:** Beads automatically creates these worktrees when using the sync-branch feature to commit issue updates to a separate branch without switching your working directory. - -**If you don't want these:** -```bash -# Disable sync-branch feature -bd config set sync.branch "" - -# Clean up existing worktrees -rm -rf .git/beads-worktrees -rm -rf .git/worktrees/beads-* -git worktree prune -``` - -See [WORKTREES.md](WORKTREES.md) for details on how beads uses worktrees. - -### Dolt remote sync not working - -Check if Dolt server is running and configured: - -```bash -# Check if Dolt server is running -bd doctor - -# Manual sync with Dolt remotes -bd dolt push -bd dolt pull - -# Check sync configuration -bd config get sync.remote -``` - -## Ready Work and Dependencies - -### `bd ready` shows nothing but I have open issues - -Those issues probably have open blockers. Check: - -```bash -# See blocked issues -bd blocked - -# Show dependency tree (default max depth: 50) -bd dep tree - -# Limit tree depth to prevent deep traversals -bd dep tree --max-depth 10 - -# Remove blocking dependency if needed -bd dep remove -``` - -Remember: Only `blocks` dependencies affect ready work. - -### Circular dependency errors - -bd prevents dependency cycles, which break ready work detection. To fix: - -```bash -# Detect all cycles -bd dep cycles - -# Remove the dependency causing the cycle -bd dep remove - -# Or redesign your dependency structure -``` - -### Dependencies not showing up - -Check the dependency type: - -```bash -# Show full issue details including dependencies -bd show - -# Visualize the dependency tree -bd dep tree -``` - -Remember: Different dependency types have different meanings: -- `blocks` - Hard blocker, affects ready work -- `related` - Soft relationship, doesn't block -- `parent-child` - Hierarchical (child depends on parent) -- `discovered-from` - Work discovered during another issue - -## Performance Issues - -### Export/import is slow - -For large databases (10k+ issues): - -```bash -# Export only open issues -bd export --format=jsonl --status=open -o open-issues.jsonl - -# Or filter by priority -bd export --format=jsonl --priority=0 --priority=1 -o critical.jsonl -``` - -Consider splitting large projects into multiple databases. - -### Commands are slow - -Check database size and consider compaction: - -```bash -# Check database stats -bd stats - -# Preview compaction candidates -bd admin compact --dry-run --all - -# Compact old closed issues -bd admin compact --days 90 - -# Run Dolt garbage collection -cd .beads/dolt && dolt gc -``` - -Consider splitting large projects into multiple databases: -```bash -cd ~/project/component1 && bd init --prefix comp1 -cd ~/project/component2 && bd init --prefix comp2 -``` - -## Agent-Specific Issues - -### Agent creates duplicate issues - -Agents may not realize an issue already exists. Prevention strategies: - -- Have agents search first: `bd list --json | grep "title"` -- Use labels to mark auto-created issues: `bd create "..." -l auto-generated` -- Review and deduplicate periodically: `bd list | sort` -- Use `bd merge` to consolidate duplicates: `bd merge bd-2 --into bd-1` - -### Agent gets confused by complex dependencies - -Simplify the dependency structure: - -```bash -# Check for overly complex trees -bd dep tree - -# Remove unnecessary dependencies -bd dep remove - -# Use labels instead of dependencies for loose relationships -bd label add related-to-feature-X -``` - -### Agent can't find ready work - -Check if issues are blocked: - -```bash -# See what's blocked -bd blocked - -# See what's actually ready -bd ready --json - -# Check specific issue -bd show -bd dep tree -``` - -### MCP server not working - -Check installation and configuration: - -```bash -# Verify MCP server is installed -pip list | grep beads-mcp - -# Check MCP configuration -cat ~/Library/Application\ Support/Claude/claude_desktop_config.json - -# Test CLI works -bd version -bd ready - -# Check Dolt server health -bd doctor -``` - -See [integrations/beads-mcp/README.md](../integrations/beads-mcp/README.md) for MCP-specific troubleshooting. - -### Sandboxed environments (Codex, Claude Code, etc.) - -**Issue:** Sandboxed environments restrict permissions, preventing server control and causing "out of sync" errors. - -**Common symptoms:** -- "Database out of sync" errors that persist after running `bd dolt pull` -- `bd dolt stop` fails with "operation not permitted" -- Hash mismatch warnings (bd-160) - -**Root cause:** The sandbox can't signal/kill the existing Dolt server process. - ---- - -#### Quick fix: Sandbox mode (auto-detected) - -**As of v0.21.1+**, bd automatically detects sandboxed environments and enables sandbox mode. - -When auto-detected, you'll see: `ℹ️ Sandbox detected, using direct mode` - -**Manual override** (if auto-detection fails): - -```bash -# Explicitly enable sandbox mode -bd --sandbox ready -bd --sandbox create "Fix bug" -p 1 -bd --sandbox update bd-42 --claim -``` - -**What sandbox mode does:** -- Uses embedded database mode (no server needed) -- Disables auto-export -- Disables auto-import -- Allows bd to work in network-restricted environments - -**Note:** You'll need to manually sync when outside the sandbox: -```bash -# After leaving sandbox, sync manually -bd dolt push -``` - ---- - -#### Escape hatches for stuck states - -If you're stuck in a "database out of sync" loop with a running server you can't stop, use these flags: - -**1. Force metadata update** - -If staleness persists after pulling: - -```bash -# Force metadata refresh -bd doctor --fix - -# This updates internal metadata tracking without changing issues -# Fixes: stuck state caused by stale server cache -``` - -**2. Use sandbox mode (preferred)** - -```bash -# Most reliable for sandboxed environments -bd --sandbox ready -bd --sandbox dolt pull -``` - ---- - -#### Troubleshooting workflow - -If stuck in a sandboxed environment: - -```bash -# Step 1: Try sandbox mode (cleanest solution) -bd --sandbox ready - -# Step 2: If you get staleness errors, force fix -bd doctor --fix - -# Step 3: When back outside sandbox, sync normally -bd dolt push -``` - ---- - -#### Understanding the flags - -| Flag | Purpose | When to use | Risk | -|------|---------|-------------|------| -| `--sandbox` | Use embedded mode, disable Dolt auto-push | Sandboxed environments (Codex, containers) | Low - safe for sandboxes | -| `bd doctor --fix` | Force metadata update | Stuck staleness loop | Low - updates metadata only | - -**Related:** -- See [Claude Code sandboxing documentation](https://www.anthropic.com/engineering/claude-code-sandboxing) for more about sandbox restrictions -- GitHub issue [#353](https://github.com/gastownhall/beads/issues/353) for background - -## Platform-Specific Issues - -### Windows: Path issues - -```pwsh -# Check if bd.exe is in PATH -where.exe bd - -# Add Go bin to PATH (permanently) -[Environment]::SetEnvironmentVariable( - "Path", - $env:Path + ";$env:USERPROFILE\go\bin", - [EnvironmentVariableTarget]::User -) - -# Reload PATH in current session -$env:Path = [Environment]::GetEnvironmentVariable("Path", "User") -``` - -### Windows: Firewall blocking Dolt server - -The Dolt server listens on loopback TCP. Allow `bd.exe` through Windows Firewall: - -1. Open Windows Security β†’ Firewall & network protection -2. Click "Allow an app through firewall" -3. Add `bd.exe` and enable for Private networks -4. Or disable firewall temporarily for testing - -### Windows: Controlled Folder Access blocks bd init - -**Symptom:** `bd init` hangs indefinitely with high CPU usage, and CTRL+C doesn't work. - -**Cause:** Windows Controlled Folder Access is blocking `bd.exe` from creating the `.beads` directory. - -**Diagnosis:** Run with verbose flag to see the actual error: -```pwsh -bd init -v -# Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified -``` - -**Solution:** Add `bd.exe` to the Controlled Folder Access whitelist: - -1. Open Windows Security β†’ Virus & threat protection -2. Click "Ransomware protection" β†’ "Manage ransomware protection" -3. Under "Controlled folder access", click "Allow an app through Controlled folder access" -4. Click "Add an allowed app" β†’ "Browse all apps" -5. Navigate to and select `bd.exe` (typically in `%USERPROFILE%\go\bin\bd.exe`) -6. Retry `bd init` - it should work instantly - -**Note:** Unlike typical blocked apps, Controlled Folder Access may not show a notification when blocking `bd init`, making this issue hard to diagnose without the `-v` flag. - -### macOS: Gatekeeper blocking execution - -If macOS blocks bd: - -1. Verify the downloaded binary checksum matches the release `checksums.txt`. -2. If you used `scripts/install.sh`, note that macOS ad-hoc re-signing is now **opt-in** (`BEADS_INSTALL_RESIGN_MACOS=1`). -3. Use one of the approval paths below. - -```bash -# Remove quarantine attribute -xattr -d com.apple.quarantine /usr/local/bin/bd - -# Or allow in System Preferences -# System Preferences β†’ Security & Privacy β†’ General β†’ "Allow anyway" -``` - -### Linux: Permission denied - -If you get permission errors: - -```bash -# Make bd executable -chmod +x /usr/local/bin/bd - -# Or install to user directory -mkdir -p ~/.local/bin -mv bd ~/.local/bin/ -export PATH="$HOME/.local/bin:$PATH" -``` - -## Getting Help - -If none of these solutions work: - -1. **Check existing issues**: [GitHub Issues](https://github.com/gastownhall/beads/issues) -2. **Enable debug logging**: `bd --verbose ` -3. **File a bug report**: Include: - - bd version: `bd version` - - OS and architecture: `uname -a` - - Error message and full command - - Steps to reproduce -4. **Join discussions**: [GitHub Discussions](https://github.com/gastownhall/beads/discussions) - -## Related Documentation - -- **[README.md](../README.md)** - Core features and quick start -- **[ADVANCED.md](ADVANCED.md)** - Advanced features -- **[FAQ.md](FAQ.md)** - Frequently asked questions -- **[INSTALLING.md](INSTALLING.md)** - Installation guide diff --git a/docs/architecture/dolt.md b/docs/architecture/dolt.md index 005d0d593..723a5148b 100644 --- a/docs/architecture/dolt.md +++ b/docs/architecture/dolt.md @@ -589,8 +589,8 @@ On machines with multiple beads projects, each project normally starts its own D Shared server mode runs a single Dolt server at `~/.beads/shared-server/` that serves all projects: ```bash -# Enable for this project -bd dolt set shared-server true +# Enable for this project (config.yaml key) +bd config set dolt.shared-server true # Or enable machine-wide via environment variable export BEADS_DOLT_SHARED_SERVER=1 diff --git a/docs/architecture/index.md b/docs/architecture/index.md index 2de268b3d..d8c347b0f 100644 --- a/docs/architecture/index.md +++ b/docs/architecture/index.md @@ -1,9 +1,9 @@ --- title: Architecture Overview -description: "Understanding Beads' three-layer data model" +description: "How Beads stores, queries, and syncs issue data with Dolt" --- -This document explains how Beads' architecture works with Dolt as its storage backend. +This document explains how Beads' architecture works with Dolt as its storage backend: the storage layout, the data model, and the sync paths. For the concept model β€” beads, dependencies, ready work, molecules β€” see [How Beads Works](/core-concepts/index). ## Architecture @@ -16,7 +16,7 @@ running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section ```mermaid flowchart TD subgraph DOLT["πŸ—„οΈ Dolt Database"] - D[(".beads/dolt/
Version-Controlled SQL")] + D[("embedded default: .beads/embeddeddolt/
server mode: .beads/dolt/
Version-Controlled SQL")] end subgraph REMOTE["🌐 Dolt Remotes"] @@ -48,6 +48,44 @@ Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or res - **Works offline**: All queries run against local database - **Portable**: `bd export` produces JSONL for migration and interoperability +## Data Model + +The database stores five kinds of records: issues (the beads themselves), dependencies (typed edges such as `blocks`, `parent-child`, `related`, and `discovered-from`), labels, comments, and events (the audit trail). What each means β€” and how `bd ready` computes the claimable frontier from them β€” is covered in [How Beads Works](/core-concepts/index). + +Issue IDs are content-derived hashes (`bd-a1b2`) so that concurrent writers never collide and no central ID coordination is needed. See [Hash-based IDs](/core-concepts/hash-ids) for the design and [COLLISION_MATH](https://github.com/gastownhall/beads/blob/main/engdocs/COLLISION_MATH.md) for the birthday-paradox analysis of hash length vs collision probability. + +### Issue Schema + +Core fields on every issue, as stored in Dolt and emitted in `bd export` JSONL. Optional fields are omitted when empty. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique hash ID (e.g., `bd-a1b2`) | +| `title` | string | Issue title (required) | +| `description` | string | Detailed description (optional) | +| `design` | string | Design notes (optional) | +| `acceptance_criteria` | string | Acceptance criteria (optional) | +| `notes` | string | Additional notes (optional) | +| `status` | string | `open`, `in_progress`, `blocked`, `deferred`, `closed`, `pinned`, `hooked` (defaults to `open`; extendable via the `status.custom` config key) | +| `priority` | int | 0–4, where 0 = critical and 4 = backlog | +| `issue_type` | string | `bug`, `feature`, `task`, `epic`, `chore`, `decision`, `message`, `molecule`, `gate`, `spike`, `story`, `milestone` (defaults to `task`) | +| `assignee` | string | Assigned user/agent (optional) | +| `estimated_minutes` | int | Time estimate in minutes (optional) | +| `created_at` / `updated_at` | RFC3339 | Creation and last-modification times | +| `created_by` | string | Who created the issue (optional) | +| `closed_at` / `close_reason` | RFC3339 / string | Set when the issue is closed (optional) | +| `external_ref` | string | External reference such as `gh-9` or `jira-ABC` (optional) | +| `metadata` | JSON | Arbitrary extension data β€” see [Issue Metadata](/core-concepts/metadata) | +| `labels` | []string | Tags attached to the issue (optional) | +| `dependencies` | []Dependency | Typed edges to other issues (optional) | +| `comments` | []Comment | Discussion thread (optional) | + +Issues also carry workflow-layer field groups, among others: scheduling (`due_at`, `defer_until`), claim leasing (`lease_expires_at`, `heartbeat_at`), gates (`await_type`, `await_id`, `timeout`), and molecule/wisp fields (`ephemeral`, `mol_type`, `bonded_from`). + +Internal fields β€” `content_hash` (a SHA-256 of the issue's canonical content, used for change detection), `source_repo`, and `id_prefix` β€” never appear in exports. + +The schema is stable by default: prefer the `metadata` field for integration-, orchestrator-, or team-specific data before proposing new first-class fields. See the [Project Charter's schema boundary](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#schema-boundary). + ## Data Flow ### Write Path @@ -73,6 +111,10 @@ User runs bd dolt pull β†’ Remote commits fetched and merged ``` +Dolt remotes can live on DoltHub, S3, GCS, a filesystem path, or your existing git remote β€” issue history rides under `refs/dolt/data`, separate from code branches. See [Sync Concepts](/core-concepts/sync-concepts) for the wire format and setup. + +Cross-repo setups can also exchange beads peer-to-peer via [federation](/multi-agent/federation). Ephemeral [wisps](/workflows/wisps) are excluded from federation push by default, so execution traces never enter shared history. + ### Multi-Machine Sync Considerations When working across multiple machines or clones: @@ -99,7 +141,9 @@ The Dolt server handles background synchronization and database operations: - Manages the Dolt database backend - Handles auto-commit for change tracking - Provides concurrent access for multiple agents -- Logs available at `.beads/dolt/sql-server.log` +- Runtime files live directly in `.beads/`: `dolt-server.pid`, `dolt-server.log`, and `dolt-server.port` + +An opt-in *shared server* mode runs a single Dolt server at `~/.beads/shared-server/` for all projects, enabled with `dolt.shared-server: true` in `config.yaml` or `BEADS_DOLT_SHARED_SERVER=1` β€” see [Dolt Backend](/architecture/dolt#shared-server-mode). Start the Dolt server with `bd dolt start`. Check health with `bd doctor`. @@ -107,14 +151,14 @@ Start the Dolt server with `bd dolt start`. Check health with `bd doctor`. ### Embedded Mode (No Server) -For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running: +Embedded mode is the default (`bd init` with no flags): Dolt runs in-process, single-writer, with data at `.beads/embeddeddolt/` β€” no server process and no separate Dolt install. Server mode is opt-in via `bd init --server`; the choice is persisted in `.beads/metadata.json`. ```bash bd create "CI-generated issue" bd dolt push ``` -**When embedded mode is appropriate:** +**Beyond solo use, embedded mode is a natural fit for:** - CI/CD pipelines (Jenkins, GitHub Actions) - Docker containers - Ephemeral environments @@ -137,6 +181,20 @@ When multiple git clones of the same repository run sync operations simultaneous See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2). +## Directory Layout + +```text +.beads/ +β”œβ”€β”€ embeddeddolt/ # Dolt database (embedded mode, default) β€” gitignored +β”œβ”€β”€ dolt/ # Dolt database (server mode) β€” gitignored +β”œβ”€β”€ dolt-server.pid # Server-mode runtime files (.pid, .log, .port) β€” gitignored +β”œβ”€β”€ issues.jsonl # Passive JSONL export for viewers and interchange +β”œβ”€β”€ metadata.json # Backend config β€” tracked in git +└── config.yaml # Project config (optional) β€” tracked in git +``` + +The database directory for your mode is the only thing holding issue data; everything else is configuration, runtime state, or a derived export. `bd init` writes a `.beads/.gitignore` that keeps the database and runtime files out of git. + ## Recovery Model Dolt's version control makes recovery straightforward: @@ -145,6 +203,8 @@ Dolt's version control makes recovery straightforward: 2. **Have a backup?** β†’ Restore it: `bd backup restore [path] --force` 3. **Merge conflicts?** β†’ Dolt handles cell-level merge natively +Create backups with `bd backup init` (a filesystem path or DoltHub destination) and push them with `bd backup sync`. Dolt-native backups preserve full commit history; a JSONL export does not. + ### Universal Recovery Sequence The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery/index). @@ -189,10 +249,10 @@ Beads is designed for offline-first, local-first development. The Dolt server ru | Benefit | Trade-off | |---------|-----------| | Works offline | No real-time collaboration | -| Version-controlled database | Requires Dolt server | +| Version-controlled database | Server mode needed for concurrent writers | | Cell-level merge | Requires initial setup | | Local-first speed | Manual sync to remotes | -| SQL queries | Dolt binary dependency | +| SQL queries | Dolt storage engine dependency | ### When NOT to use Beads @@ -201,13 +261,18 @@ Beads is not suitable for: - **Large teams (10+)** β€” Git-based sync doesn't scale well for high-frequency concurrent edits - **Non-developers** β€” Requires Git and command-line familiarity - **Real-time collaboration** β€” No live updates; requires explicit sync -- **Cross-repository tracking** β€” Issues are scoped to a single repository - **Rich media attachments** β€” Designed for text-based issue tracking For these use cases, consider GitHub Issues, Linear, or Jira. ## Related Documentation +- [How Beads Works](/core-concepts/index) β€” The concept model: beads, dependencies, ready work, molecules +- [Sync Concepts](/core-concepts/sync-concepts) β€” Cross-machine sync, wire format, and anti-patterns +- [Dolt Backend](/architecture/dolt) β€” Embedded vs server mode in depth, shared server, migration +- [Storage Backends](/architecture/storage-backends) β€” Postgres, MySQL, and SQLite alternatives - [Recovery Runbooks](/recovery/index) β€” Step-by-step procedures for common issues - [CLI Reference](/cli-reference/index) β€” Complete command documentation - [Getting Started](/index) β€” Installation and first steps +- [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) β€” Product scope and boundaries (contributor doc) +- [Internals](https://github.com/gastownhall/beads/blob/main/engdocs/INTERNALS.md) β€” Implementation details (contributor doc) diff --git a/docs/getting-started/ide-setup.md b/docs/getting-started/ide-setup.md index 70f63c486..3406fb2c7 100644 --- a/docs/getting-started/ide-setup.md +++ b/docs/getting-started/ide-setup.md @@ -2,27 +2,118 @@ title: IDE Setup --- -Configure your IDE for optimal beads integration. +Configure your IDE or coding agent for optimal beads integration. + +Last reviewed: 2026-07-10 + +Freshness source: `cmd/bd/setup*.go` and `internal/recipes/`. + +## How `bd setup` Works + +The `bd setup` command uses a **recipe-based architecture**: recipes define where beads workflow instructions are written. Built-in recipes cover popular tools, and you can add custom recipes for any other tool (see Custom Recipes below). Integrations complement each other β€” you can install several at once. + +```bash +bd setup --list # Show all available recipes +bd setup claude # Install an integration (claude, cursor, gemini, ...) +bd setup claude --check # Verify installation +bd setup claude --remove # Uninstall +``` + +| Recipe | Files written | Details | +|--------|---------------|---------| +| `claude` | `.claude/settings.json` (or `~/.claude/settings.json` with `--global`) + `CLAUDE.md` section | [Claude Code](/integrations/claude-code) | +| `cursor` | `.cursor/rules/beads.mdc` + `.cursor/hooks.json` + `.agents/skills/beads/` | [Cursor](/integrations/cursor) | +| `gemini` | `~/.gemini/settings.json` (or `.gemini/settings.json` with `--project`) + `GEMINI.md` section | [Gemini CLI](/integrations/gemini) | +| `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | [Copilot CLI](/integrations/copilot-cli) | +| `codex` | `.agents/skills/beads/` + `AGENTS.md` section + `.codex/` hooks | [Codex](/integrations/codex) | +| `factory` | `AGENTS.md` section | [Factory.ai Droid](/integrations/factory) | +| `mux` | `AGENTS.md` section (+ `.mux/` layers with `--project`/`--global`) | [Mux](/integrations/mux) | +| `opencode` | `AGENTS.md` section | [OpenCode](/integrations/opencode) | +| `aider` | `.aider.conf.yml` + `.aider/BEADS.md` + `.aider/README.md` | [Aider](/integrations/aider) | +| `junie` | `.junie/guidelines.md` + `.junie/mcp/mcp.json` | [Junie](/integrations/junie) | +| `windsurf` | `.windsurf/rules/beads.md` | [Windsurf](/integrations/windsurf) | +| `cody` | `.cody/rules/beads.md` | [Cody](/integrations/cody) | +| `kilocode` | `.kilocode/rules/beads.md` | [Kilo Code](/integrations/kilocode) | + +`bd prime` is the single source of truth for operational workflow commands. Each integration's instruction file either points to `bd prime` (hook-enabled agents) or carries the full command reference (AGENTS-first agents). + + +Commit the instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, as applicable) to git so all team members and AI tools get the same instructions. + + +### Template Profiles + +Each integration writes one of two **profiles** that control how much content goes into the tool's instruction file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`): + +| Profile | Used by | Content | +|---------|---------|---------| +| `full` | Factory, Mux, OpenCode | Complete command reference, issue types, priorities, workflow | +| `minimal` | Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) | + +Hook-enabled agents use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Codex is skill-based instead: it uses `.agents/skills/beads/SKILL.md`, with managed `AGENTS.md` guidance telling Codex when to use the skill. + +**Profile precedence:** if a file already has a `full` profile section and a `minimal` profile tool installs to the same file (for example via symlinks), the `full` profile is preserved to avoid information loss. + +### Policy Profiles + +Template profiles control how much text gets installed. Policy profiles control what an agent is authorized to do at handoff: + +| Policy | Default scope | Commit/push guidance | +|--------|---------------|----------------------| +| `conservative` | Standalone projects, unknown projects, and one-off assistance | Use `bd` for task tracking, then report changed files, validation, and proposed commands. Do not commit, push, or run Dolt remote sync without explicit user or orchestrator approval. | +| `minimal` | Hook-first integrations where `bd prime` carries the detailed workflow | Same git authority as conservative; the installed file stays short and points to `bd prime`. | +| `team-maintainer` | Repositories that explicitly delegate session close to agents | Agents may close beads, run quality gates, commit, run `bd dolt push`, and `git push` as part of routine work. Current "do not commit" or "do not push" instructions still override the profile. | + +The generated beads section and `bd prime` default to conservative git authority. Set the profile explicitly with the `agent.profile` config key or the `BD_AGENT_PROFILE` environment variable (values: `conservative`, `minimal`, `team-maintainer`; the env var takes precedence; an unrecognized value falls back to `conservative`): + +```bash +bd config set agent.profile team-maintainer +# or, for a single session/process: +BD_AGENT_PROFILE=team-maintainer bd prime +``` + +`bd prime` layers this explicit knob on top of its per-branch git-authority checks (stealth mode, no git remote, ephemeral branch, `no-push`); those hard constraints still take precedence, and `team-maintainer` remains subordinate to any explicit "do not commit"/"do not push" instruction. Beads never infers team-maintainer authority merely because a remote exists β€” it must be set via this knob (or, for tools without config access, via top-level project instructions). + +### Managed Sections + +`bd setup factory`, `bd setup mux`, and `bd setup opencode` append a beads section to `AGENTS.md`, wrapped in `BEGIN/END BEADS INTEGRATION` HTML-comment markers. The begin marker carries version, profile, and hash metadata (e.g. ``) so `--check` can report `missing`, `stale`, or `current`; legacy markers without metadata are auto-upgraded on the next install or update. Re-running setup updates the existing section in place (idempotent), and `--remove` deletes only the managed section β€” the rest of your `AGENTS.md` is untouched. + +`bd setup codex` uses its own marker pair (`BEGIN/END BEADS CODEX SETUP`). Running it alongside `bd setup factory` or `bd setup mux` against the same `AGENTS.md` leaves two managed sections side by side; each recipe's `--check` inspects only its own section, and each `--remove` removes only its own section. + +One `AGENTS.md` works across many tools β€” Factory Droid, Mux, OpenCode, Cursor, Zed, Jules, and other AGENTS.md-aware assistants β€” so `bd setup factory` is a good starting point when your team mixes AI tools. ## Claude Code The recommended approach for Claude Code: ```bash -# Setup Claude Code integration -bd setup claude +bd setup claude # Project install: .claude/settings.json +bd setup claude --global # Global install: ~/.claude/settings.json ``` This installs: -- **SessionStart hook** - Runs `bd prime` when Claude Code starts -- **SessionStart compact refresh** - Runs `bd prime` after context compaction +- **SessionStart hook** - Runs `bd prime --hook-json`, which wraps the workflow context in the JSON envelope Claude Code expects. SessionStart fires when a session starts, resumes, or clears, and again after context compaction β€” no separate compaction hook is needed. +- **Minimal beads section in `CLAUDE.md`** - A pointer to `bd prime`, managed with hash/version markers for safe updates and `--check` freshness detection. + +If the [beads Claude Code plugin](/integrations/claude-code-plugin) is installed, hooks are plugin-managed and `bd setup claude` skips writing them, so `bd prime` doesn't fire twice per session. **How it works:** -1. SessionStart hook runs `bd prime` automatically +1. SessionStart hook runs `bd prime --hook-json` automatically 2. `bd prime` injects ~1-2k tokens of workflow context 3. You use `bd` CLI commands directly 4. Git hooks refresh exports and legacy fallbacks; Dolt remotes handle sync +**Flags:** + +| Flag | Description | +|------|-------------| +| `--check` | Check both hooks and the managed `CLAUDE.md` beads section | +| `--remove` | Remove beads hooks and the managed `CLAUDE.md` beads section | +| `--global` | Install to `~/.claude/settings.json` instead of the project | +| `--stealth` | Use `bd prime --stealth --hook-json` (flush only, no git operations) β€” useful in CI/CD where git operations might fail | + +Restart Claude Code after installation for the hooks to take effect. + **Verify installation:** ```bash bd setup claude --check @@ -30,13 +121,19 @@ bd setup claude --check ### Manual Setup -If you prefer manual configuration, add to your Claude Code hooks: +If you prefer manual configuration, add the hook to your Claude Code settings: ```json { "hooks": { - "SessionStart": ["bd prime"], - "SessionStart": ["bd prime"] + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { "type": "command", "command": "bd prime --hook-json" } + ] + } + ] } } ``` @@ -44,17 +141,35 @@ If you prefer manual configuration, add to your Claude Code hooks: ## Cursor IDE ```bash -# Setup Cursor integration -bd setup cursor +bd setup cursor # Rules file + agent hooks + beads skill +bd setup cursor --global # Global hooks in ~/.cursor/hooks.json ``` -This creates `.cursor/rules/beads.mdc` with beads-aware rules. +This creates `.cursor/rules/beads.mdc` with beads-aware rules, `.cursor/hooks.json` with agent hooks (prime on session start, restore context after compaction), and the beads agent skill in `.agents/skills/beads/`. **Verify:** ```bash bd setup cursor --check ``` +See [Cursor](/integrations/cursor) for hook details and PATH caveats. + +## Gemini CLI + +```bash +bd setup gemini # Global hooks in ~/.gemini/settings.json +bd setup gemini --project # Project hooks in .gemini/settings.json +``` + +This installs a SessionStart hook running `bd prime --hook-json` β€” Gemini requires hook stdout to be valid JSON, and `--hook-json` wraps the markdown in the required envelope β€” plus a minimal beads section in `GEMINI.md`. `--stealth` works the same as for Claude Code; `--check` and `--remove` cover both the hooks and the managed `GEMINI.md` section. + +**Verify:** +```bash +bd setup gemini --check +``` + +See [Gemini CLI](/integrations/gemini) for details. + ## Aider ```bash @@ -62,16 +177,45 @@ bd setup cursor --check bd setup aider ``` -This creates/updates `.aider.conf.yml` with beads context. +This writes three files: + +| File | Purpose | +|------|---------| +| `.aider.conf.yml` | Points Aider to read the instructions file | +| `.aider/BEADS.md` | Workflow instructions for the AI | +| `.aider/README.md` | Quick reference for humans | + +Aider is human-in-the-loop: the AI **suggests** `bd` commands, and you run them with `/run`. See [Aider](/integrations/aider) for the workflow. **Verify:** ```bash bd setup aider --check ``` +## AGENTS.md Tools: Factory, Mux, OpenCode, Codex + +```bash +bd setup factory # Factory.ai Droid β€” AGENTS.md section +bd setup mux # Mux β€” AGENTS.md section (+ --project/--global layers) +bd setup opencode # OpenCode β€” AGENTS.md section +bd setup codex # Codex β€” beads skill + AGENTS.md guidance + native hooks +``` + +These create or update a managed section in `AGENTS.md` (see Managed Sections above). `bd init` runs the project Codex setup automatically unless `--skip-agents` or `--stealth` is used. In worktree, shared, or `BEADS_DIR` setups, use `bd where` to confirm the resolved workspace β€” these integrations do not require a local `./.beads`. Restart the tool after setup if it is already running. + +Details: [Factory.ai Droid](/integrations/factory), [Mux](/integrations/mux), [OpenCode](/integrations/opencode), [Codex](/integrations/codex). + ## GitHub Copilot -For VS Code with GitHub Copilot, use the MCP server: +**Copilot CLI:** + +```bash +bd setup copilot +``` + +This installs a native Copilot CLI plugin manifest (`.copilot-plugin/plugin.json`, which registers `bd prime` hooks) and repository instructions (`.github/copilot-instructions.md`). See [Copilot CLI](/integrations/copilot-cli). + +**For VS Code with GitHub Copilot**, use the MCP server: ```bash # Install MCP server @@ -134,7 +278,7 @@ This outputs a compact (~1-2k tokens) workflow reference including: `bd prime` prints memories near the top and starts with a truncation warning. If your host stores the full hook output in a file and only shows a preview, have the agent read the full file before continuing. -For memory-only hooks: +In hook contexts, `bd prime --hook-json` wraps the output in the SessionStart JSON envelope (Claude Code, Gemini CLI, Codex). For memory-only hooks: ```bash bd prime --memories-only @@ -172,6 +316,44 @@ Add to Claude Desktop config: See [MCP Server](/integrations/mcp-server) for detailed configuration. +## Custom Recipes + +For editors or tools without a built-in recipe: + +```bash +bd setup --add myeditor .myeditor/rules.md # Save a custom recipe +bd setup myeditor # Install it +bd setup myeditor --check # Check it +bd setup myeditor --remove # Remove it +``` + +Custom recipes are stored in `.beads/recipes.toml` (adding one requires an active beads workspace): + +```toml +[recipes.myeditor] +name = "myeditor" +path = ".myeditor/rules.md" +type = "file" +``` + +For a one-off install without saving a recipe, write the template to any path β€” or inspect it first: + +```bash +bd setup -o .my-custom-location/beads.md +bd setup --print +``` + +**Recipe types:** + +| Type | Description | Used by | +|------|-------------|---------| +| `file` | Write the template to a single file | windsurf, cody, kilocode | +| `hooks` | Modify JSON settings to add hooks | claude, gemini | +| `section` | Inject a marked section into an existing file | factory, codex, mux, opencode | +| `multifile` | Write multiple files | aider, copilot, junie | + +Custom recipes added via `--add` are always type `file`. + ## Git Hooks Ensure git hooks are installed for export refresh and legacy fallback behavior: @@ -181,13 +363,16 @@ bd hooks install ``` This installs: -- **pre-commit** - Validates changes before commit -- **post-merge** - Imports changes after pull -- **pre-push** - Ensures sync before push +- **pre-commit** - Runs chained hooks before commit +- **post-merge** - Runs chained hooks after pull/merge +- **pre-push** - Runs chained hooks before push +- **post-checkout** - Runs chained hooks after branch checkout +- **prepare-commit-msg** - Adds agent identity trailers for forensics **Check hook status:** ```bash -bd info # Shows warnings if hooks are outdated +bd hooks list # Installed, outdated, or missing +bd info # Shows warnings if hooks are outdated ``` ## Verifying Your Setup @@ -198,12 +383,16 @@ Run a complete health check: # Check version bd version -# Check project health +# Check project health (includes integration status) bd doctor -# Check hooks -bd hooks status +# Check git hooks +bd hooks list # Check editor integration -bd setup claude --check # or cursor, aider +bd setup claude --check # or cursor, gemini, aider, ... ``` + +**Troubleshooting:** +- *Hooks not working?* Restart your AI tool after installation, then re-run `bd setup claude --check` (or your tool's recipe) and check `bd doctor` output for integration status. +- *Context not appearing?* Make sure `bd prime` works standalone; if it fails, fix the underlying beads issue first. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index ce3887543..774a0c59f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -168,7 +168,7 @@ brew install beads CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest ``` -**Via go install** (embedded-capable): +**Via go install** (embedded-capable, needs Xcode CLI tools): ```bash CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` @@ -196,12 +196,14 @@ yay -S beads-git paru -S beads-git ``` +Thanks to [@v4rgas](https://github.com/v4rgas) for maintaining the AUR package! + **Via go install** (server-mode only): ```bash CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest ``` -**Via go install** (embedded-capable): +**Via go install** (embedded-capable, needs gcc): ```bash CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` @@ -231,18 +233,32 @@ Beads ships with native Windows supportβ€”no MSYS or MinGW required. irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex ``` -The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source. +The script installs a prebuilt Windows release if available and verifies the downloaded ZIP checksum against release `checksums.txt`. Go is only required for `go install` or building from source. **Via go install** (server-mode only): ```pwsh $env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest ``` -**Via go install** (embedded-capable): +This produces a server-mode-only binary with no C compiler requirement β€” the fastest path to a working `bd` on Windows. + +**Via go install** (embedded-capable, needs MinGW-w64 gcc on your PATH): ```pwsh $env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest ``` +**From source**: +```pwsh +git clone https://github.com/gastownhall/beads +cd beads +make build +Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\ +``` + +**Windows notes:** +- The Dolt server listens on a loopback TCP endpoint +- Allow `bd.exe` loopback traffic through any host firewall + ## IDE and Editor Integrations ### CLI + Hooks (Recommended) @@ -259,6 +275,7 @@ bd init --quiet # 3. Setup editor integration (choose one) bd setup claude # Claude Code - installs SessionStart hooks +bd setup copilot # GitHub Copilot CLI - creates .copilot-plugin/plugin.json + .github/copilot-instructions.md bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc bd setup aider # Aider - creates .aider.conf.yml bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks @@ -269,7 +286,7 @@ bd setup mux # Mux - creates/updates AGENTS.md **How it works:** - `bd init` creates or updates `AGENTS.md` and installs project Claude/Codex integrations by default unless you use `--skip-agents` or `--stealth` - Editor hooks/rules inject `bd prime` automatically on session start -- Codex 0.129.0+ uses native `/hooks` for startup and compaction-aware context refresh +- Codex 0.129.0+ uses native `/hooks`: SessionStart injects `bd prime`, compact hooks mark context stale, and the next prompt after compaction refreshes Beads context once - `bd prime` provides ~1-2k tokens of workflow context - You use `bd` CLI commands directly - Git hooks (installed by `bd init`) refresh exports and legacy fallbacks; `bd dolt push/pull` syncs the database @@ -280,6 +297,38 @@ bd setup mux # Mux - creates/updates AGENTS.md - **Lower latency** - Direct CLI calls, no MCP protocol overhead - **Universal** - Works with any editor that has shell access +**Verify installation:** every recipe supports a check flag, e.g. `bd setup claude --check` or `bd setup copilot --check`. + +### Claude Code Plugin (Optional) + +For enhanced UX with slash commands: + +```bash +# In Claude Code +/plugin marketplace add gastownhall/beads +/plugin install beads +# Restart Claude Code +``` + +The plugin adds: +- Slash commands: `/beads:ready`, `/beads:create`, `/beads:show`, `/beads:update`, `/beads:close`, etc. +- Task agent for autonomous execution + +See [Claude Code Plugin](/integrations/claude-code-plugin) for complete plugin documentation. + +### GitHub Copilot + +For **VS Code with GitHub Copilot**, install the MCP server (`uv tool install beads-mcp`) and create `.vscode/mcp.json` in your project β€” or add it to the VS Code user-level MCP config to enable it for all projects. See [GitHub Copilot](/integrations/github-copilot) for the complete setup guide, including the user-level config paths per platform. + +For the **GitHub Copilot CLI** terminal integration: + +```bash +bd setup copilot # Install project Copilot plugin + repository instructions +bd setup copilot --check # Verify the project integration files exist +``` + +This setup is currently project-scoped only. It writes `.copilot-plugin/plugin.json` and `.github/copilot-instructions.md`; there is no separate `--global` or `--project` mode for Copilot today, and it does not manage `~/.copilot/...` paths. See [Copilot CLI](/integrations/copilot-cli) for the full guide. + ### MCP Server (Alternative) Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell): @@ -306,6 +355,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: } ``` +For Sourcegraph Amp configuration and detailed MCP server documentation, see [MCP Server](/integrations/mcp-server). + ## Verifying Installation After installing, verify bd is working: @@ -317,6 +368,8 @@ bd help ## Troubleshooting +For additional troubleshooting, see [Troubleshooting](/reference/troubleshooting). + ### `bd: command not found` bd is not in your PATH: @@ -341,6 +394,33 @@ This is typically caused by CGO/SQLite compatibility issues: CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` +If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please [file an issue](https://github.com/gastownhall/beads/issues). + +### Claude Code Plugin: MCP server fails to start + +If the Claude Code plugin's MCP server fails immediately after installation, it's likely that `uv` is not installed or not in your PATH. + +**Symptoms:** +- Plugin slash commands work, but MCP tools are unavailable +- Error logs show `command not found: uv` +- Server fails silently on startup + +**Solution:** +```bash +# Install uv +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Restart your shell or update PATH +source ~/.local/bin/env + +# Verify uv is available +which uv + +# Restart Claude Code +``` + +See [Claude Code Plugin](/integrations/claude-code-plugin) for alternative installation methods. + ## Updating bd Upgrade checklist: @@ -382,8 +462,22 @@ irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex brew upgrade beads ``` +### npm + +```bash +npm update -g @beads/bd +``` + +### bun + +```bash +bun install -g --trust @beads/bd +``` + ### go install +Use whichever mode you installed with originally: + ```bash # Server-mode only CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest @@ -392,8 +486,25 @@ CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` +### From source + +```bash +cd beads +git pull +make build +sudo mv bd /usr/local/bin/ +``` + +Prereleases (e.g. release candidates) are published only as GitHub prereleases +and are not pushed to the stable Homebrew/npm/PyPI channels, so `brew upgrade` +and friends will not move you onto them β€” fetch the prerelease build explicitly. + For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading). +## Uninstalling + +To completely remove Beads from a repository, see [Uninstalling](/recovery/uninstalling). + ## Next Steps After installation: @@ -401,3 +512,4 @@ After installation: 1. **Initialize a project**: `cd your-project && bd init` 2. **Learn the basics**: See [Quick Start](/getting-started/quickstart) 3. **Configure your agent**: See [IDE Setup](/getting-started/ide-setup), or run `bd setup --list` +4. **Explore examples**: Check out the [examples/](https://github.com/gastownhall/beads/tree/main/examples) directory diff --git a/docs/integrations/aider.md b/docs/integrations/aider.md index ff1a44d62..662ed3605 100644 --- a/docs/integrations/aider.md +++ b/docs/integrations/aider.md @@ -66,6 +66,24 @@ aider bd prime | aider --message-file - ``` +### Inside Aider + +Aider's own commands start with `/` (`/run`, `/add`, `/help`); anything else is a message to the AI. The AI suggests bd commands, and you execute the ones you approve with `/run`: + +```text +You: What issues are ready to work on? + +Aider: Let me check the available work. Run: +/run bd ready + +You: Let's work on bd-42 + +Aider: To claim it, run: +/run bd update bd-42 --claim +``` + +To give the AI full bd context mid-session, run `/run bd prime` β€” the AI reads the output and picks up the complete workflow guide. + ### During Work Use bd commands alongside aider: @@ -75,6 +93,9 @@ Use bd commands alongside aider: bd create "Found bug during work" --deps discovered-from:bd-42 --json bd update bd-42 --claim bd ready + +# Link an already-created issue as discovered work +bd dep add bd-77 bd-42 --type discovered-from ``` ### End Session @@ -89,6 +110,7 @@ bd dolt push 2. **Push regularly** - Run `bd dolt push` after significant changes 3. **Use discovered-from** - Track issues found during work 4. **Document context** - Include descriptions in issues +5. **Aider commits, bd syncs** - Aider auto-commits your code changes; issue data moves separately with `bd dolt push` ## Example Workflow @@ -121,6 +143,8 @@ cat .aider.conf.yml bd setup aider ``` +Aider reads `.aider.conf.yml` at startup, so restart aider (`/exit`, then `aider`) after regenerating. + ### Issues not visible ```bash @@ -135,3 +159,6 @@ bd doctor - [Claude Code](/integrations/claude-code) - [IDE Setup](/getting-started/ide-setup) +- [Quickstart](/getting-started/quickstart) +- [Aider documentation](https://aider.chat/docs/) +- [AGENTS.md](https://github.com/gastownhall/beads/blob/main/AGENTS.md) - the full bd agent workflow guide diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md index a8eb29bcd..460dd20af 100644 --- a/docs/integrations/claude-code.md +++ b/docs/integrations/claude-code.md @@ -13,22 +13,40 @@ bd setup claude ``` This installs: -- **SessionStart hook** - Runs `bd prime` on session start -- **SessionStart compact refresh** - Runs `bd prime` after context compaction +- **SessionStart hook** - Runs `bd prime --hook-json` when a session starts. SessionStart also fires after context compaction, so the same hook refreshes context automatically. +- **CLAUDE.md pointer** - A minimal beads section in your project's `CLAUDE.md` (skipped if `CLAUDE.md` is a symlink). + +By default the hook is written to the project's `.claude/settings.json`. Variants: + +```bash +bd setup claude --global # Install to ~/.claude/settings.json instead +bd setup claude --stealth # Stealth mode: flush only, no git operations +bd setup claude --remove # Remove the hook and the CLAUDE.md section +``` + +If the [beads plugin](/integrations/claude-code-plugin) is enabled, `bd setup claude` skips writing hooks - the plugin provides its own, and duplicates would run `bd prime` twice per session. ### Manual Setup -Add to your Claude Code hooks configuration: +Add to `.claude/settings.json` (project) or `~/.claude/settings.json` (global): ```json { "hooks": { - "SessionStart": ["bd prime"], - "SessionStart": ["bd prime"] + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { "type": "command", "command": "bd prime --hook-json" } + ] + } + ] } } ``` +The `--hook-json` flag wraps the output in the hook JSON envelope Claude Code expects. No `PreCompact` hook is needed - SessionStart fires again after compaction. + ### Verify Setup ```bash @@ -39,8 +57,16 @@ bd setup claude --check 1. **Session starts** β†’ `bd prime` injects ~1-2k tokens of context 2. **You work** β†’ Use `bd` CLI commands directly -3. **Session compacts** β†’ `bd prime` refreshes workflow context before compaction -4. **Session ends** β†’ Changes synced via git +3. **Session compacts** β†’ SessionStart fires again and `bd prime` refreshes workflow context +4. **Session ends** β†’ `bd dolt push` syncs changes + +### Why CLI + hooks instead of MCP? + +Context efficiency. MCP tool schemas can add 10-50k tokens to every request; `bd prime` adds ~1-2k tokens of workflow context - 10-50x less overhead, which means lower cost, lower latency, and better model attention. Prefer CLI + hooks in any environment with shell access; use the [MCP server](/integrations/mcp-server) only where the CLI is unavailable, such as Claude Desktop. + +### Why not Claude Skills? + +Beads doesn't ship or require Claude Skills (`.claude/skills/`). `bd prime` already delivers the workflow context, and the workflow fits a simple command set (ready β†’ create β†’ update β†’ close β†’ sync). Skills are also Claude-specific, which would break beads' editor-agnostic approach - the same CLI works in Cursor, Windsurf, and every other shell-capable editor. You can create your own Skills on top of beads, but none are needed. ## Essential Commands for Agents @@ -130,7 +156,7 @@ bd dolt push ## Plugin (Optional) -For enhanced UX with slash commands: +For slash commands and enhanced UX, install the [beads plugin](/integrations/claude-code-plugin): ```bash # In Claude Code @@ -177,5 +203,6 @@ bd init --quiet ## See Also +- [Beads Claude Code Plugin](/integrations/claude-code-plugin) - Packaged plugin with slash commands - [MCP Server](/integrations/mcp-server) - For MCP-only environments - [IDE Setup](/getting-started/ide-setup) - Other editors diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md index bd5ec0965..f46d603e9 100644 --- a/docs/integrations/codex.md +++ b/docs/integrations/codex.md @@ -29,4 +29,47 @@ Codex 0.129.0+ supports `/hooks`, compact lifecycle hooks, and hook-provided dev `PreCompact` alone does not inject context because Codex ignores plain stdout from compact hooks. The post-compact marker plus first-prompt refresh is the reliable recovery path. -The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them as `"hooks": "./hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`. +Refresh markers are stored in a user cache/temp directory keyed by Codex `session_id` and workspace path. They are not written to tracked files or to the Beads database. + +The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them in `plugins/beads/.codex-plugin/plugin.json` as `"hooks": "./.codex-plugin/hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`. + +## Manual Fallback + +If you manage `.codex/hooks.json` by hand instead of running `bd setup codex`, the equivalent shape is: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|resume|clear", + "hooks": [{ "type": "command", "command": "bd codex-hook SessionStart", "statusMessage": "Loading Beads context" }] + } + ], + "PreCompact": [ + { + "matcher": "manual|auto", + "hooks": [{ "type": "command", "command": "bd codex-hook PreCompact", "statusMessage": "Checking Beads context" }] + } + ], + "PostCompact": [ + { + "matcher": "manual|auto", + "hooks": [{ "type": "command", "command": "bd codex-hook PostCompact", "statusMessage": "Scheduling Beads context refresh" }] + } + ], + "UserPromptSubmit": [ + { + "hooks": [{ "type": "command", "command": "bd codex-hook UserPromptSubmit", "statusMessage": "Refreshing Beads context" }] + } + ] + } +} +``` + +Then ensure `.codex/config.toml` enables: + +```toml +[features] +hooks = true +``` diff --git a/docs/integrations/github-copilot.md b/docs/integrations/github-copilot.md index b776c1c28..bb26a40dc 100644 --- a/docs/integrations/github-copilot.md +++ b/docs/integrations/github-copilot.md @@ -2,7 +2,16 @@ title: GitHub Copilot --- -How to use beads with GitHub Copilot in VS Code. +Beads gives Copilot a persistent, structured memory for tracking work: with the MCP server configured, you create, update, and track issues in natural language without leaving the editor. + +This page covers **Copilot Chat in VS Code via MCP**. For the terminal-based Copilot CLI plugin installed by `bd setup copilot`, see [Copilot CLI](/integrations/copilot-cli). + +## Prerequisites + +- VS Code 1.96+ with the GitHub Copilot extension +- A GitHub Copilot subscription (Individual, Business, or Enterprise) +- The beads CLI installed ([installation guide](/getting-started/installation)) +- Python 3.10+ or the `uv` package manager ## Setup @@ -10,7 +19,12 @@ How to use beads with GitHub Copilot in VS Code. 1. Install beads-mcp: ```bash + # Using uv (recommended) uv tool install beads-mcp + + # Or using pip / pipx + pip install beads-mcp + pipx install beads-mcp ``` 2. Create `.vscode/mcp.json` in your project: @@ -48,6 +62,8 @@ How to use beads with GitHub Copilot in VS Code. bd init --quiet ``` + This creates a `.beads/` directory with the issue database. + 4. Reload VS Code ### Verify Setup @@ -65,22 +81,36 @@ Copilot: Created bd-42: Login timeout bug You: What issues are ready? Copilot: 3 issues ready: bd-42, bd-99, bd-17 -You: Close bd-42, it's fixed -Copilot: Closed bd-42 +You: Claim bd-42, I'll take it +Copilot: Claimed bd-42 and started work + +You: I found a related bug - the session token isn't refreshed. + File it, linked to bd-42. +Copilot: Created bd-103: Session token not refreshed + Linked as discovered-from bd-42 + +You: Close bd-42 with reason "Fixed timeout handling" +Copilot: Closed bd-42: Fixed timeout handling ``` +Syncing stays on the CLI: run `bd dolt push` at the end of a session. There is no MCP push tool. + ## MCP Tools -| Tool | Description | -|------|-------------| -| `beads_ready` | List unblocked issues | -| `beads_create` | Create new issue | -| `beads_show` | Show issue details | -| `beads_update` | Update issue | -| `beads_close` | Close issue | -| `beads_dolt_push` | Push to Dolt remote | -| `beads_dep_add` | Add dependency | -| `beads_dep_tree` | Show dependency tree | +| Tool | Description | You say | +|------|-------------|---------| +| `ready` | List unblocked issues | "What can I work on?" | +| `list` | List issues with filters | "Show all open bugs" | +| `show` | Show issue details, including dependencies and dependents | "Show bd-42 details" | +| `create` | Create new issue | "Create a task for refactoring" | +| `claim` | Atomically claim an issue (assignee + in_progress) | "I'll take bd-42" | +| `update` | Update issue fields | "Set bd-42 to priority 1" | +| `close` | Close an issue | "Complete bd-42" | +| `dep` | Add dependency | "bd-99 blocks bd-42" | +| `blocked` | Show blocked issues and their blockers | "What's blocking my work?" | +| `stats` | Issue counts and average lead time | "How's the backlog?" | + +The server also exposes `reopen`, `comment`, `comments`, `note`, `context`, and `admin`; call `discover_tools` for the full catalog. ## Copilot Instructions @@ -96,9 +126,18 @@ Quick reference: - `bd ready` - Find unblocked work - `bd create "Title" --type task --priority 2` - Create issue - `bd close ` - Complete work -- `bd dolt push` - Push changes to Dolt remote +- `bd dolt push` - Push changes to Dolt remote (run at session end) ``` +## CLI vs MCP + +| Approach | Best for | Trade-off | +|----------|----------|-----------| +| **MCP (Copilot Chat)** | Natural language, discovery | Higher token overhead | +| **CLI (terminal)** | Scripting, precision, speed | Requires shell access | + +Both work against the same database - use MCP for conversational work, the CLI for quick commands. See [MCP Server](/integrations/mcp-server) for the full trade-off discussion. + ## Troubleshooting ### Tools not appearing @@ -113,6 +152,13 @@ Quick reference: ```bash # Check installation which beads-mcp +beads-mcp --version + +# uv installs to ~/.local/bin - make sure it's on PATH +export PATH="$HOME/.local/bin:$PATH" + +# If installed with pip, find it +pip show beads-mcp | grep Location # Reinstall if needed uv tool install beads-mcp --force @@ -124,6 +170,18 @@ uv tool install beads-mcp --force bd init --quiet ``` +### Changes not persisting + +Push to the Dolt remote at the end of your session, from the terminal: + +```bash +bd dolt push +``` + +### Organization policies blocking MCP + +For Copilot Business/Enterprise, your organization must enable the "MCP servers in Copilot" policy. Contact your admin if MCP tools don't appear despite a correct config. + ## FAQ ### Do I need to clone beads? @@ -132,10 +190,20 @@ bd init --quiet ### What about git hooks? -Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`. +Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`. They never modify your source code; skip them with `bd init --skip-hooks`. + +### Can I use beads without Copilot? + +Yes. The same database works from the terminal, [Claude Code](/integrations/claude-code), [Cursor](/integrations/cursor), [Aider](/integrations/aider), and any editor with MCP or shell access. + +### Does this work with Copilot in other editors? + +This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MCP; the config location differs. For Neovim, use the CLI directly. For the terminal, see [Copilot CLI](/integrations/copilot-cli). ## See Also - [MCP Server](/integrations/mcp-server) - Detailed MCP configuration +- [Copilot CLI](/integrations/copilot-cli) - Terminal-based Copilot integration +- [Quickstart](/getting-started/quickstart) - bd command basics - [Installation](/getting-started/installation) - Full install guide -- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation +- [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference diff --git a/docs/integrations/mcp-server.md b/docs/integrations/mcp-server.md index 00a343d19..eda8b8879 100644 --- a/docs/integrations/mcp-server.md +++ b/docs/integrations/mcp-server.md @@ -113,15 +113,23 @@ The MCP server exposes these tools: | Tool | Description | |------|-------------| -| `beads_create` | Create new issue | -| `beads_list` | List issues | -| `beads_show` | Show issue details | -| `beads_update` | Update issue | -| `beads_close` | Close issue | -| `beads_ready` | Show ready work | -| `beads_sync` | Sync to git | -| `beads_dep_add` | Add dependency | -| `beads_dep_tree` | Show dependency tree | +| `ready` | Show ready work (no open blockers) | +| `list` | List issues with filters | +| `show` | Show issue details, dependencies, and dependents | +| `create` | Create a new issue | +| `claim` | Atomically claim an issue | +| `update` | Update an issue | +| `close` / `reopen` | Close or reopen an issue | +| `dep` | Manage dependencies | +| `comment` / `comments` | Add or list comments | +| `note` | Append to an issue's notes | +| `blocked` | Show blocked issues and their blockers | +| `stats` / `context` | Database stats and workspace context | +| `admin` | Administrative operations | +| `discover_tools` / `get_tool_info` | Tool discovery and schemas | + +There is no MCP sync tool β€” syncing stays on the CLI (`bd dolt push` / +`bd dolt pull`). ## Usage diff --git a/docs/multi-agent/coordination.md b/docs/multi-agent/coordination.md index 16ec4a277..890b1748c 100644 --- a/docs/multi-agent/coordination.md +++ b/docs/multi-agent/coordination.md @@ -6,32 +6,35 @@ Patterns for coordinating work between multiple AI agents. ## Work Assignment -### Pinning Work +### Assigning and Claiming Work -Assign work to a specific agent: +Assign work to a specific agent, or claim it atomically for yourself: ```bash -# Pin issue to agent -bd pin bd-42 --for agent-1 +# Assign issue to an agent +bd assign bd-42 agent-1 -# Pin and start work -bd pin bd-42 --for agent-1 --start +# Atomically claim an issue (sets assignee to you, status to in_progress) +bd update bd-42 --claim -# Unpin work -bd unpin bd-42 +# Claim the first ready issue matching your filters +bd ready --claim --json + +# Release a claimed issue +bd unclaim bd-42 ``` -### Checking Pinned Work +### Checking Assigned Work ```bash -# What's on my hook? -bd hook +# What is agent-1 working on? +bd list --assignee agent-1 --status in_progress -# What's on agent-1's hook? -bd hook --agent agent-1 +# What is ready for agent-1? +bd ready --assignee agent-1 # JSON output -bd hook --json +bd list --assignee agent-1 --json ``` ## Handoff Patterns @@ -42,11 +45,11 @@ Agent A completes work, hands off to Agent B: ```bash # Agent A -bd close bd-42 --reason "Ready for review" -bd pin bd-42 --for agent-b +bd comment bd-42 "API complete, ready for review" +bd assign bd-42 agent-b # Agent B picks up -bd hook # Sees bd-42 +bd list --assignee agent-b # Sees bd-42 bd update bd-42 --claim ``` @@ -56,11 +59,13 @@ Multiple agents work on different issues: ```bash # Coordinator -bd pin bd-42 --for agent-a --start -bd pin bd-43 --for agent-b --start -bd pin bd-44 --for agent-c --start +bd assign bd-42 agent-a +bd assign bd-43 agent-b +bd assign bd-44 agent-c + +# Each agent claims its issue and works independently +bd update bd-42 --claim -# Each agent works independently # Coordinator monitors progress bd list --status in_progress --json ``` @@ -75,51 +80,59 @@ bd create "Part A" --parent bd-epic bd create "Part B" --parent bd-epic bd create "Part C" --parent bd-epic -bd pin bd-epic.1 --for agent-a -bd pin bd-epic.2 --for agent-b -bd pin bd-epic.3 --for agent-c +bd assign bd-epic.1 agent-a +bd assign bd-epic.2 agent-b +bd assign bd-epic.3 agent-c -# Fan-in: wait for all parts -bd dep add bd-merge bd-epic.1 bd-epic.2 bd-epic.3 +# Fan-in: wait for all parts (one dependency per call) +bd dep add bd-merge bd-epic.1 +bd dep add bd-merge bd-epic.2 +bd dep add bd-merge bd-epic.3 ``` + +For structured epic fan-out, `bd swarm` creates and tracks a swarm molecule +from an epic (`bd swarm create`, `bd swarm status`). + + ## Agent Discovery -Find available agents: +Beads has no agent registry β€” assignees are plain strings. To see which +agents are active, group in-progress work by assignee: ```bash -# List known agents (if using agent registry) -bd agents list - -# Check agent status -bd agents status agent-1 +bd list --status in_progress --json ``` ## Conflict Prevention -### File Reservations +### Atomic Claims -Prevent concurrent edits: +`--claim` is atomic: when multiple agents pull from the same ready queue, +the first claim wins, and repeating a claim you already hold is idempotent. +Prefer claiming over assigning when agents self-select work: ```bash -# Reserve files before editing -bd reserve auth.go --for agent-1 - -# Check reservations -bd reservations list - -# Release when done -bd reserve --release auth.go +bd ready --claim --json ``` -### Issue Locking +### Merge Slots + +Serialize conflict-prone work (such as merge-queue conflict resolution) with +a merge slot β€” an exclusive-access primitive only one agent can hold at a +time. Each project has one merge slot bead, named from the issue prefix +(e.g. `bd-merge-slot`): ```bash -# Lock issue for exclusive work -bd lock bd-42 --for agent-1 +# Create the merge slot for this project +bd merge-slot create -# Unlock when done -bd unlock bd-42 +# Check availability +bd merge-slot check + +# Acquire before starting; release when done +bd merge-slot acquire +bd merge-slot release ``` ## Communication Patterns @@ -128,10 +141,10 @@ bd unlock bd-42 ```bash # Agent A leaves note -bd comment add bd-42 "Completed API, needs frontend integration" +bd comment bd-42 "Completed API, needs frontend integration" # Agent B reads -bd show bd-42 --full +bd comments bd-42 ``` ### Via Labels @@ -144,10 +157,26 @@ bd update bd-42 --add-label "needs-review" bd list --label-any needs-review ``` +## Coordinating Across Repositories + +Agents can coordinate work that spans repositories: + +```bash +# Depend on a capability delivered by another project +bd dep add bd-42 external:backend:api-ready +``` + +Multi-repo routing, aggregated views, and contributor/team workflows are +covered in [Routing](/multi-agent/routing) and +[Multi-Repo Migration](/multi-agent/multi-repo-migration). + ## Best Practices -1. **Clear ownership** - Always pin work to specific agent +1. **Clear ownership** - Assign or claim work so every issue has one owner 2. **Document handoffs** - Use comments to explain context 3. **Use labels for status** - `needs-review`, `blocked`, `ready` -4. **Avoid conflicts** - Use reservations for shared files +4. **Avoid conflicts** - Claim atomically; use merge slots to serialize + conflict-prone work 5. **Monitor progress** - Regular status checks +6. **Sync at session end** - Run `bd dolt push` so other agents see your + updates diff --git a/docs/multi-agent/index.md b/docs/multi-agent/index.md index 328f860ad..0f9fd1676 100644 --- a/docs/multi-agent/index.md +++ b/docs/multi-agent/index.md @@ -13,15 +13,12 @@ Multi-agent features enable: ## Key Concepts -### Routes +### Routing -Routes define which repository handles which issues: - -```jsonl -{"pattern": "frontend/*", "target": "frontend-repo"} -{"pattern": "backend/*", "target": "backend-repo"} -{"pattern": "*", "target": "main-repo"} -``` +Routing decides which repository a new bead lands in, based on your role +(contributor vs maintainer) and the `routing.*` config keys β€” an explicit +`--repo` flag always wins. See [Multi-Repo Routing](/multi-agent/routing) +for the decision flow and configuration reference. ### Work Assignment diff --git a/docs/multi-agent/multi-repo-migration.md b/docs/multi-agent/multi-repo-migration.md index 6fadfcf1b..e0cf317fa 100644 --- a/docs/multi-agent/multi-repo-migration.md +++ b/docs/multi-agent/multi-repo-migration.md @@ -16,7 +16,7 @@ This guide helps you adopt beads' multi-repo workflow for OSS contributions, tea ## What is Multi-Repo Mode? -By default, beads stores issues in its Dolt database within `.beads/dolt/` in your current repository. Multi-repo mode lets you: +By default, beads stores issues in its Dolt database under `.beads/` in your current repository (`.beads/embeddeddolt/` in the default embedded mode). Multi-repo mode lets you: - **Route issues to different repositories** based on your role (maintainer vs. contributor) - **Aggregate issues from multiple repos** into a unified view @@ -371,7 +371,7 @@ bd config get routing.maintainer bd config get routing.contributor # Check detected role -bd info --json | jq '.role' +bd config get beads.role # Override with explicit flag bd create "Issue" -p 1 --repo . diff --git a/docs/multi-agent/routing.md b/docs/multi-agent/routing.md index 5b18374e3..6a2da06ce 100644 --- a/docs/multi-agent/routing.md +++ b/docs/multi-agent/routing.md @@ -1,112 +1,286 @@ --- -title: Routing +title: Multi-Repo Routing --- -Automatic issue routing across repositories. +One agent often works across more than one repository: an OSS fork plus a +private planning repo, a planning repo feeding an implementation repo, several +project checkouts on one machine. **Routing** decides which repository's +database receives each new bead, so a contributor's planning never pollutes +upstream PRs while a maintainer's beads land straight in the project. -## Overview +Routing is opt-in. With no routing configuration, every bead lands in the +current repository β€” nothing on this page changes single-repo workflows. -Routing enables: -- Issues created in one repo routed to another -- Pattern-based routing rules -- Fallback to default repository +## The contributor problem -## Configuration +You fork an OSS project that uses beads. Every planning bead you create writes +to the fork's `.beads/` data, and your fork's issue database now diverges from +upstream in every PR you open. What you want is to plan freely *about* the +project without planning *in* the project. -Create `.beads/routes.jsonl`: +Routing solves this by detecting your role and redirecting `bd create` to a +separate planning repository (`~/.beads-planning` by default) that is never +pushed upstream. -```jsonl -{"pattern": "frontend/**", "target": "frontend-repo", "priority": 10} -{"pattern": "backend/**", "target": "backend-repo", "priority": 10} -{"pattern": "docs/**", "target": "docs-repo", "priority": 5} -{"pattern": "*", "target": "main-repo", "priority": 0} +## How routing decides + +When you run `bd create`, the target repository is chosen in strict +precedence order: + +1. `--repo ` β€” explicit override, always wins +2. `routing.mode: auto` β€” route by detected role (maintainer or contributor) +3. `routing.default` β€” everything else (defaults to `.`, the current repo) + +```mermaid +flowchart TD + A["bd create"] --> B{"--repo flag set?"} + B -- "yes" --> C["Explicit target repo"] + B -- "no" --> D{"routing.mode = auto?"} + D -- "no" --> E["routing.default target
(default: current repo)"] + D -- "yes" --> F{"Detected role"} + F -- "maintainer" --> G["routing.maintainer target
(default: current repo)"] + F -- "contributor" --> H["routing.contributor target
(default: ~/.beads-planning)"] ``` -## Route Fields +Reads follow the same routing: with routing active, `bd list` and `bd ready` +read from the routed repository, and ID lookups like `bd show` fall back to +the routed repository when a bead isn't found locally. -| Field | Description | -|-------|-------------| -| `pattern` | Glob pattern to match | -| `target` | Target repository | -| `priority` | Higher = checked first | +## Role detection -## Pattern Matching - -Patterns match against: -- Issue title -- Labels -- Explicit path prefix - -**Examples:** -```jsonl -{"pattern": "frontend/*", "target": "frontend"} -{"pattern": "*api*", "target": "backend"} -{"pattern": "label:docs", "target": "docs-repo"} -``` - -## Commands +The role that drives auto mode comes from git config β€” `beads.role` is the +source of truth: ```bash -# Show routing table -bd routes list -bd routes list --json - -# Test routing -bd routes test "Fix frontend button" -bd routes test --label frontend - -# Add route -bd routes add "frontend/**" --target frontend-repo --priority 10 - -# Remove route -bd routes remove "frontend/**" +bd config set beads.role contributor # stored in git config, not the database +bd config get beads.role ``` -## Auto-Routing +When `beads.role` is unset, `bd` prints a warning and falls back to a +deprecated remote-URL heuristic: -When creating issues, beads checks routes: +| Git remote situation | Detected role | +|---|---| +| `origin` and `upstream` point at different repos (fork workflow) | contributor | +| SSH `origin` (`git@...`, `ssh://`) or credentialed HTTPS | maintainer | +| Plain HTTPS `origin` without credentials | contributor | +| No remote configured (local project) | maintainer | + + +SSH does not reliably indicate push access β€” fork contributors often clone +over SSH. Set `beads.role` explicitly and the heuristic (and its warning) +never runs. + + +## Setup + +### Contributors ```bash -bd create "Fix frontend button alignment" -t bug -# Auto-routed to frontend-repo based on title match +cd ~/projects/my-fork +bd init --contributor ``` -Override with explicit target: +The interactive wizard: + +1. Creates the planning repository (`~/.beads-planning` by default) as its + own git repo with a `.beads/` directory +2. Sets `routing.mode: auto` and `routing.contributor` to the planning repo +3. Adds the planning repo to `repos.additional` so routed beads stay visible + (see [hydration](#multi-repo-hydration)) +4. On forks, points sync at the `upstream` remote so `bd dolt pull` fetches + issue data from the source repo rather than your fork + +Plain `bd init` also detects the fork pattern (an `upstream` remote that +differs from `origin`) and applies the same contributor configuration +automatically; pass `--role maintainer` to opt out. + +If you created planning beads in the project database before configuring +routing, [`bd migrate-personal`](/cli-reference/migrate-personal) moves the +beads created by your git identity into your planning repo. + +### Teams ```bash -bd create "Fix button" --repo backend-repo +bd init --team ``` -## Cross-Repo Dependencies - -Track dependencies across repos: +Teams sharing one repository usually need no routing: with routing unset, +every bead lands in the shared repo. The team wizard configures the rest of +the shared workflow β€” team mode and, for protected-main setups, a separate +sync branch for issue commits. Team members who want a private scratch space +route experiments explicitly: ```bash -# In frontend-repo -bd dep add bd-42 external:backend-repo/bd-100 - -# View cross-repo deps -bd dep tree bd-42 --cross-repo +bd create "Try alternative approach" --repo ~/.beads-planning-personal ``` -## Hydration +Full step-by-step walkthroughs for both scenarios (plus multi-phase and +multi-persona setups) live in +[Multi-Repo Migration](/multi-agent/multi-repo-migration). -Pull related issues from other repos: +## Configuration reference + +Set these with `bd config set `; see the +[configuration reference](/reference/configuration) for storage locations. + +| Key | Default | Meaning | +|---|---|---| +| `routing.mode` | (unset) | `auto` routes by role; `explicit` (or unset) sends everything to `routing.default` | +| `routing.default` | `.` | Target when auto mode is off | +| `routing.maintainer` | `.` | Target for maintainers in auto mode | +| `routing.contributor` | `~/.beads-planning` | Target for contributors in auto mode | +| `repos.primary` | (unset) | Primary repo for multi-repo hydration | +| `repos.additional` | (unset) | Repos to hydrate beads from | +| `beads.role` | (unset) | Explicit role: `maintainer` or `contributor` (stored in git config) | + +Verify the effective configuration and where each value comes from: ```bash -# Hydrate issues from related repos -bd hydrate - -# Preview hydration -bd hydrate --dry-run - -# Hydrate specific repo -bd hydrate --from backend-repo +bd config show # all sources: config.yaml, database, git, env +bd config validate # checks routing.mode value and related settings +bd where # which database this directory actually uses ``` -## Best Practices +## Overriding per bead -1. **Use specific patterns** - Avoid overly broad matches -2. **Set priorities** - Ensure specific patterns match first -3. **Default fallback** - Always have a `*` pattern with lowest priority -4. **Test routes** - Use `bd routes test` before committing +`--repo` bypasses routing entirely for one bead: + +```bash +bd create "Fix upstream bug" --repo . # force current repo +bd create "Private experiment" --repo ~/scratch # force another repo +``` + +## Discovered work stays with its parent + +A bead created with a `discovered-from` dependency inherits its parent's +`source_repo`, so work discovered while executing a task stays attributed to +the same repository as that task β€” regardless of your role: + +```bash +bd create "Found race in auth" --deps discovered-from:bd-abc +# inherits bd-abc's source_repo +``` + +Add `--repo` to override the inheritance. + +## Multi-repo hydration + +Routing writes beads to another repository β€” which means your current +database doesn't contain them. **Hydration** imports beads from other repos +into your database, each tagged with its `source_repo`, so `bd list` and +`bd ready` show one unified view. + +Configure it by listing the other repos in `repos.additional`: + +```bash +bd repo add ~/.beads-planning # add a repo to hydrate from +bd repo list # show primary + additional repos +bd repo sync # import beads from all additional repos +bd repo remove ~/.beads-planning # remove, deleting its hydrated beads +``` + +`bd repo sync` reads each additional repo's `.beads/issues.jsonl` export and +imports the beads with their original prefixes and `source_repo` set, +skipping repos whose export hasn't changed. `bd init --contributor` wires +hydration up automatically; `bd doctor` warns when routing targets are +missing from `repos.additional`. + +Once hydrated, beads from other repos are ordinary rows in your database β€” +filter by provenance or link them with normal dependencies: + +```bash +bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")' +bd dep add impl-42 plan-10 --type blocks +``` + +For dependencies on *capabilities* of another project rather than specific +beads, `bd dep add` also accepts `external::` targets β€” +see [`bd dep`](/cli-reference/dep). + +## One agent, many projects + +An AI agent working across several repositories should run a *single* beads +MCP server instance: + +```json +{ + "beads": { + "command": "beads-mcp", + "args": [] + } +} +``` + +The server resolves the beads workspace from each request's working +directory, so one configuration serves every project while each project keeps +its own isolated database (embedded Dolt at `.beads/embeddeddolt/` by +default; server mode uses `.beads/dolt/`). Running one MCP instance per +project invites operations landing in the wrong database. + +To share one Dolt server across all projects instead of embedded per-project +storage, initialize with `bd init --shared-server` (or set +`BEADS_DOLT_SHARED_SERVER=1`): projects share a server at +`~/.beads/shared-server/` while staying isolated in per-project databases +named after their issue prefixes. See [MCP Server](/integrations/mcp-server) +for installation and client configuration. + +## Troubleshooting + +### Beads land in the wrong repository + +```bash +bd config get routing.mode # auto? +bd config get beads.role # explicit role set? +bd config show --source git # what git config contributes +``` + +Fix by setting the role explicitly (`bd config set beads.role maintainer`), +forcing the target for one bead (`--repo .`), or disabling role detection +entirely (`bd config set routing.mode explicit`). + +### Routed beads don't appear in bd list + +The routing target isn't being hydrated. Add it and sync: + +```bash +bd repo add ~/.beads-planning +bd repo sync +``` + +`bd doctor` catches this misconfiguration. + +### Discovered beads appear in the "wrong" repo + +Intentional β€” beads with a `discovered-from` dependency inherit the parent's +`source_repo`. Override with `--repo` at creation time. + +### Planning beads show up in upstream PRs + +The planning repo must be a separate git repository, never committed to the +fork: + +```bash +ls ~/.beads-planning/.git # should exist +bd config get routing.contributor # should point at the planning repo +``` + +### Role warning on every bd create + +`bd` warns when it falls back to the URL heuristic. Silence it permanently: + +```bash +bd config set beads.role maintainer # or contributor +``` + +## Related pages + +- [Multi-Repo Migration](/multi-agent/multi-repo-migration) β€” full setup + walkthroughs for contributor, team, and multi-phase workflows +- [Agent Coordination](/multi-agent/coordination) β€” assigning and claiming + work between agents +- [Federation](/multi-agent/federation) β€” peer-to-peer sharing of beads + across repos and organizations +- [`bd init`](/cli-reference/init), [`bd config`](/cli-reference/config), + [`bd repo`](/cli-reference/repo), [`bd create`](/cli-reference/create) β€” + command reference diff --git a/docs/reference/advanced.md b/docs/reference/advanced.md index e90843e91..f8e4d80e7 100644 --- a/docs/reference/advanced.md +++ b/docs/reference/advanced.md @@ -18,19 +18,49 @@ Updates: - All references in other issues - Comments and descriptions -## Issue Merge +## Prefix Rename -Merge duplicate issues: +Change the issue prefix for every issue in the database β€” for example, +shortening `knowledge-work-` to `kw-`: ```bash -bd merge bd-42 bd-43 --into bd-41 -bd merge bd-42 bd-43 --into bd-41 --dry-run +bd rename-prefix kw- --dry-run # Preview without applying +bd rename-prefix kw- # Every knowledge-work-* ID becomes kw-* ``` -What gets merged: -- Dependencies β†’ target -- Text references updated across all issues -- Source issues closed with merge reason +The rename updates all issue IDs and all text references across all fields. +Prefixes are at most 8 characters of lowercase letters, numbers, and hyphens, +must start with a letter, and must end with a hyphen. If a corrupted database +contains issues with multiple prefixes, `bd rename-prefix --repair` +consolidates them. See [bd rename-prefix](/cli-reference/rename-prefix). + +## Duplicate Detection and Merge + +Find issues with identical content (title, description, design, acceptance +criteria) and consolidate them: + +```bash +bd duplicates # Report duplicate groups with suggested actions +bd duplicates --dry-run # Preview what --auto-merge would do +bd duplicates --auto-merge # Merge every duplicate group +``` + +Issues are grouped by content hash, and only when their statuses match (open +with open, closed with closed). The merge target is the most-referenced issue +in each group, falling back to the smallest ID. For each group, `--auto-merge`: + +- Re-parents children of the duplicates onto the target +- Closes the duplicates with reason `Duplicate of ` +- Links each duplicate to the target with a `related` dependency + +To mark a single known duplicate manually: + +```bash +bd duplicate bd-42 --of bd-41 # Close bd-42 as a duplicate of bd-41 +``` + +Closing is permanent, but Dolt version history preserves the original state. +Verify results with `bd show bd-41` and `bd dep tree bd-41`. ## Database Compaction @@ -57,13 +87,17 @@ bd admin cleanup --force ## Restore from History -View deleted or compacted issues from git: +Recover the pre-compaction content of a compacted issue: ```bash -bd restore bd-42 --show -bd restore bd-42 --to-file issue.json +bd restore bd-42 # Display the archived original content +bd restore bd-42 --apply # Write the original content back into the issue ``` +If no archived snapshot exists, `bd restore` falls back to a best-effort +reconstruction from Dolt version history, which can only be displayed, not +applied. + ## Database Inspection `bd sql` requires Dolt server mode (`bd dolt start`, see Performance Tuning @@ -77,7 +111,38 @@ bd info --schema --json bd sql "SELECT * FROM issues LIMIT 5" ``` -## Extension Data +## Database Redirects + +Multiple git clones can share one beads database β€” useful when several agents +or checkout directories work the same issues. Create a `.beads/redirect` file +in the secondary clone containing a single path (relative or absolute) to the +target `.beads` directory: + +```bash +# In the secondary clone +mkdir -p .beads +echo "../main-clone/.beads" > .beads/redirect +``` + +Check which database is actually in use: + +```bash +bd where # Active .beads location, including redirect info +bd where --json +``` + +Limitations and guidance: + +- Redirect chains are not followed β€” only a single level works, so a redirect + must point directly at the real `.beads` directory. +- The target directory must exist and contain a valid database. +- Give separate projects and long-lived forks their own databases instead of + redirects. +- Git worktrees don't need redirects β€” linked worktrees discover the + repository's `.beads` workspace automatically. See + [Git Worktrees](/reference/worktrees). + +## Extensible Database For Dolt-backed projects, keep extension state outside the beads database and connect it to beads through stable CLI surfaces: @@ -120,11 +185,21 @@ Events: ### Create Multiple +Bootstrap a new database from a JSONL export: + ```bash -# Bootstrap a new database from JSONL -bd init --from-jsonl issues.jsonl +# In the source project +bd export -o issues.jsonl + +# In the new project: place the export at .beads/issues.jsonl +# (or the configured import.path), then initialize from it +bd init --from-jsonl ``` +Importing records whose IDs already exist updates those issues in place β€” +hash IDs are content-derived and stable, so a matching ID is an update, not a +collision. + ### Update Multiple ```bash @@ -158,16 +233,25 @@ bd sql "SELECT id, priority, status FROM issues WHERE status != 'closed'" The storage packages under `internal/` are not a public Go API. +The [MCP server](/integrations/mcp-server) is a stateless adapter over the +same boundary: it translates MCP calls into `bd` CLI invocations and routes +each call to the correct `.beads` workspace based on the working directory. +It never caches or stores issue data itself. + ## Performance Tuning ### Large Databases ```bash -# Enable WAL mode -bd config set database.wal_mode true +# Summarize old closed issues (see Database Compaction above) +bd admin compact --stats -# Increase cache -bd config set database.cache_size 10000 +# Reclaim disk space with Dolt garbage collection +bd admin compact --dolt + +# Squash Dolt commits older than 30 days (preview first) +bd compact --dry-run +bd compact --force ``` ### Many Concurrent Agents diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 4b889d4b0..01eb18604 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -4,21 +4,27 @@ title: Configuration Complete configuration reference for beads. +Last reviewed: 2026-07-10 + +Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. + beads has two complementary configuration systems: -1. **Tool-level configuration** (YAML, managed by [Viper](https://github.com/spf13/viper)) β€” startup flags and tool behavior, stored in `config.yaml` files. +1. **Tool-level configuration** (YAML, managed by [Viper](https://github.com/spf13/viper)) β€” startup flags and tool behavior, stored in `config.yaml` files. These are user preferences: output format, auto-commit behavior, CLI ergonomics. 2. **Project-level configuration** (managed by `bd config`) β€” integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed to `config.yaml` instead (see [YAML-only keys](#yaml-only-keys-startup-settings) below). -For a deeper treatment of every namespace and its semantics, see [docs/CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md). +The split is deliberate: tool settings are user-specific; project config is team-shared and travels with the database when you run `bd dolt push`. That is also why secrets are refused in the database β€” see [Security](#security-where-secrets-live). + +Dolt is the only storage backend. Embedded mode (the default) stores data at `.beads/embeddeddolt/`; server mode (`bd init --server` or `BEADS_DOLT_SERVER_MODE=1`) uses `.beads/dolt/`. See [Dolt architecture](/architecture/dolt). ## Configuration Locations `config.yaml` is searched in this order, with later files overriding earlier ones: 1. `~/.beads/config.yaml` (legacy user-level, lowest priority) -2. `~/.config/bd/config.yaml` (XDG user-level) +2. `~/.config/bd/config.yaml` (user-level; this exact path is checked even on platforms whose native user-config directory differs) 3. `/.beads/config.yaml` (project-level, walked up from the current directory) -4. `$BEADS_DIR/config.yaml` (highest priority, when `BEADS_DIR` is set) +4. `$BEADS_DIR/config.yaml` (highest priority, when `BEADS_DIR` points at a different workspace) A `config.local.yaml` next to the project `config.yaml` is also merged in last for machine-specific overrides that should not be committed. @@ -33,6 +39,8 @@ For Viper-managed (YAML) keys, highest to lowest: Project-level keys written via `bd config set` (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override. +When a config.yaml value or environment variable shadows a database key, `bd config list` prints an override warning, and `bd config show` reports the source of every effective key. + ## Managing Configuration ```bash @@ -40,11 +48,13 @@ Project-level keys written via `bd config set` (Jira, Linear, GitHub, status map bd config set jira.url "https://company.atlassian.net" bd config set validation.on-create warn # YAML-only key -# Set many values in one go +# Set many values in one go (single auto-commit; validates before writing) bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ # Get a value bd config get jira.url +bd config get --json jira.url +# β†’ {"key":"jira.url","value":"https://company.atlassian.net"} # List all database-stored config (with override warnings) bd config list @@ -63,19 +73,21 @@ bd config unset jira.url `bd config set` automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project `config.yaml`; everything else is written to the Dolt database. `beads.role` is stored in git config. +Unrecognized keys produce a warning with a did-you-mean suggestion; use the `custom.*` namespace for user-defined keys. + ## YAML-only Keys (Startup Settings) These keys must live in `config.yaml`, not the database, because they are read before the database is opened. Writing them with `bd config set` automatically updates `config.yaml`. The full namespaces routed to YAML are: -`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*` +`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`, `metrics.*`, `list.*` Plus these individual keys: -`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `create.require-description`, `github.token`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`. +`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`. -Secrets in this list are refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`; export the value as an environment variable instead (e.g. `LINEAR_API_KEY`). +Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `password` is treated as a secret: it is refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`. Prefer exporting the value as an environment variable instead (e.g. `LINEAR_API_KEY`). ## Tool-Level Settings (config.yaml) @@ -83,32 +95,38 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p |---|---|---|---|---| | `json` | `--json` | `BD_JSON` | `false` | JSON output for scripting | | `db` | `--db` | `BD_DB` | (auto-discover) | Database path | -| `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail | +| `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail (see [Actor identity](#actor-identity-resolution)) | | `identity` | `--identity` | `BEADS_IDENTITY` | (git user / hostname) | Sender identity for `bd mail` | | `no-db` | `--no-db` | `BD_NO_DAEMON` (related) | `false` | Run without opening the database | -| `no-push` | `--no-push` | β€” | `false` | Skip pushing to Dolt remote | +| `no-push` | `--no-push` | `BD_NO_PUSH` | `false` | Skip pushing to the remote in `bd dolt push` | | `no-git-ops` | β€” | β€” | `false` | Disable git ops in `bd prime` close protocol | -| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | Create a Dolt history commit after each successful write | -| `dolt.auto-push` | β€” | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in) | +| `agent.profile` | β€” | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority: `conservative`, `minimal`, `team-maintainer`; invalid values fall back to `conservative` | +| `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by `bd prime` (0 = unlimited) | +| `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by `bd prime`, at whole-memory boundaries (0 = unlimited) | +| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | Create a Dolt history commit after each successful write (see [below](#auto-commit-sql-commits-vs-dolt-commits)) | +| `dolt.auto-push` | β€” | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in; see [below](#auto-push)) | +| `dolt.auto-push-interval` | β€” | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes | +| `dolt.auto-push-timeout` | β€” | `BD_DOLT_AUTO_PUSH_TIMEOUT` | `30s` | Timeout for a single auto-push attempt | | `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share one Dolt server at `~/.beads/shared-server/` | | `dolt.max-conns` | β€” | `BEADS_DOLT_MAX_CONNS` | `10` | Connection pool size | -| `git.author` | β€” | β€” | (none) | Override commit author for beads commits | -| `git.no-gpg-sign` | β€” | β€” | `false` | Disable GPG signing for beads commits | +| `git.author` | β€” | `BD_GIT_AUTHOR` | (none) | Override commit author for beads commits | +| `git.no-gpg-sign` | β€” | `BD_GIT_NO_GPG_SIGN` | `false` | Disable GPG signing for beads commits | | `create.require-description` | β€” | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description on `bd create` | | `validation.on-create` | β€” | `BD_VALIDATION_ON_CREATE` | `none` | Template validation: `none`, `warn`, `error` | | `validation.on-close` | β€” | `BD_VALIDATION_ON_CLOSE` | `none` | Template validation on close | | `validation.on-sync` | β€” | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync | | `validation.metadata.mode` | β€” | β€” | `none` | Metadata schema validation | | `hierarchy.max-depth` | β€” | β€” | `3` | Max hierarchical ID nesting depth | -| `backup.enabled` | β€” | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup | +| `backup.enabled` | β€” | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` (see [below](#auto-backup)) | | `backup.interval` | β€” | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups | | `backup.git-push` | β€” | β€” | `false` | Auto-push backup repo | -| `backup.git-repo` | β€” | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL | +| `backup.git-repo` | β€” | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo | | `export.auto` | β€” | β€” | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync | | `export.path` | β€” | β€” | `issues.jsonl` | Output filename relative to `.beads/` | -| `import.path` | β€” | β€” | `issues.jsonl` | Input filename relative to `.beads/` for implied JSONL imports; use relative paths for portability | | `export.interval` | β€” | β€” | `60s` | Minimum time between auto-exports | | `export.git-add` | β€” | β€” | `false` | Run `git add` on the export file | +| `import.auto` | β€” | `BD_IMPORT_AUTO` | `true` | Master switch for automatic JSONL imports: the git-hook fallback used when no Dolt remote is configured, and the empty-database recovery import when `.beads/issues.jsonl` exists but the database is empty. `false` disables all auto-imports; explicit `bd import` always works | +| `import.path` | β€” | β€” | `issues.jsonl` | Input filename relative to `.beads/` for implied JSONL imports (including `bd init --from-jsonl` and empty-DB auto-import); use relative paths for portability | | `routing.mode` | β€” | β€” | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` | | `routing.default` | β€” | β€” | `.` | Default routing target | | `routing.maintainer` | β€” | β€” | `.` | Maintainer-routed path | @@ -117,10 +135,10 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p | `directory.labels` | β€” | β€” | `{}` | Map directory patterns β†’ labels for monorepos | | `external_projects` | β€” | β€” | `{}` | Map project names β†’ paths for cross-project deps | | `federation.remote` | β€” | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL (`dolthub://`, `gs://`, `s3://`, `az://`, `file://`) | -| `federation.sovereignty` | β€” | `BD_FEDERATION_SOVEREIGNTY` | (none) | Sovereignty tier: `T1`, `T2`, `T3`, `T4` | +| `federation.sovereignty` | β€” | `BD_FEDERATION_SOVEREIGNTY` | (none) | Sovereignty tier: `T1`, `T2`, `T3`, `T4` (see [below](#sync-and-federation)) | | `federation.allowed-remote-patterns` | β€” | β€” | `[]` | Glob patterns restricting allowed remote URLs | | `federation.exclude_types` | β€” | β€” | `[wisp]` | Issue types excluded from federation push | -| `sync.require_confirmation_on_mass_delete` | β€” | β€” | `false` | Prompt before pushing >50% issue deletions | +| `sync.require_confirmation_on_mass_delete` | β€” | β€” | `false` | Prompt before pushing when a merge deletes most issues | | `output.title-length` | β€” | β€” | `255` | Title display in feedback (`0` hides); see routing note below | | `ai.model` | β€” | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model | | `agents.file` | β€” | β€” | `AGENTS.md` | Agents instruction filename; see routing note below | @@ -148,29 +166,273 @@ Routing note: `output.title-length` and `agents.file` are functionally tool-leve `bd config show` is the source of truth for what's currently effective on your machine, including provenance. +## Dolt History, Backup, and Push + +Three post-write behaviors run after each successful write command, in this order: auto-commit, auto-backup, auto-push. + +### Auto-commit: SQL Commits vs Dolt Commits + +There are two different kinds of "commit": + +- **SQL transaction commit** β€” what happens when a `bd` command updates tables successfully (durable in the Dolt *working set*). +- **Dolt version-control commit** β€” what records those changes into Dolt *history* (visible in `bd history`, and what push/pull/merge workflows operate on). + +By default (`dolt.auto-commit: on`), `bd` creates a Dolt history commit after each successful write command, so changes are never left only in the working set. The cost is more Dolt commits over time β€” one per write command β€” which is intentional; use `bd compact` to squash old history. + +Disable for a single command: + +```bash +bd --dolt-auto-commit off create "No history commit for this one" +``` + +Or in `config.yaml`: + +```yaml +dolt: + auto-commit: off +``` + +### Auto-backup + +Periodic Dolt-native backup to `.beads/backup/` provides a recovery path independent of the live database. Local Dolt commits (via `dolt.auto-commit`) remain the primary safety net; backup is a secondary layer. Unlike `bd export` or `.beads/issues.jsonl`, this is a full database backup: it preserves tables, branches, commit history, and working-set data. + +```yaml +backup: + enabled: true # Enable auto-backup after write commands + interval: 15m # Minimum time between auto-backups +``` + +How it works: + +- After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state. +- If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured). +- State is tracked in `backup_state.json` inside the backup directory. + +Manual commands (see [bd backup](/cli-reference/backup)): + +```bash +bd backup init # Register a destination (filesystem or DoltHub URL) +bd backup sync # Push to the configured destination +bd backup restore [path] # Restore from a backup (--force to overwrite) +bd backup remove # Unregister the destination +bd backup status # Show configuration and last sync time +``` + +### Auto-push + +By default, `bd` does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race. + +```yaml +dolt: + auto-push: true # Explicit opt-in; safe for single-writer setups + auto-push-interval: 5m # Minimum time between auto-pushes + auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable +``` + +How it works: + +- After each write command (after auto-commit and auto-backup), `bd` checks whether a push is due. +- Pushes are debounced: skipped if the last push was less than `dolt.auto-push-interval` ago. +- Change detection: skipped if the Dolt HEAD commit hasn't changed since the last push. +- Push failures are warnings only (non-fatal), and failed attempts are throttled too. +- Last push time and commit are tracked in `.beads/push-state.json`, a per-machine file (not in the database, to avoid merge conflicts across machines). + +Before pushing, `bd` verifies the local chunk store with `dolt fsck --quiet`, bounded by a 30-second timeout. For large stores, raise it with the runtime-only `BEADS_FSCK_TIMEOUT` environment variable (accepts durations like `2m` or bare seconds like `90`). + +## Actor Identity Resolution + +The actor name (used for `created_by` and audit trails) is resolved in this order: + +1. `--actor` flag (explicit override) +2. `BEADS_ACTOR` environment variable +3. `BD_ACTOR` environment variable (deprecated alias) +4. `git config user.name` +5. `$USER` environment variable +6. `"unknown"` (final fallback) + +For most developers no configuration is needed β€” issue authorship matches commit authorship automatically. To override, set `BEADS_ACTOR` in your shell profile: + +```bash +export BEADS_ACTOR="my-github-handle" +``` + ## Project-Level Settings (Database) These are written to the Dolt database by `bd config set` and have no env var override. Common namespaces: | Namespace | Purpose | |---|---| -| `jira.*` | Jira integration (URL, project, status_map, type_map) | -| `linear.*` | Linear integration (team_id, state_map, label_type_map, relation_map) | +| `jira.*` | Jira integration (URL, project(s), status_map, type_map, custom_fields) | +| `linear.*` | Linear integration (team_id(s), priority_map, state_map, label_type_map, relation_map) | | `github.*` | GitHub integration (org, repo, label_map) | -| `ado.*` | Azure DevOps integration (org, project, state_map, type_map) | +| `gitlab.*` | GitLab integration | +| `ado.*` | Azure DevOps integration (org, project(s), state_map, type_map) | +| `notion.*` | Notion integration | | `custom.*` | User-defined / custom integrations | -| `status.custom` | Comma-separated list of custom statuses | +| `.last_sync` | Updated automatically after each tracker sync; enables incremental sync | +| `status.custom` | Custom statuses with optional behavior categories (see [below](#custom-statuses-and-types)) | | `types.custom` | Comma-separated list of custom issue types | -| `types.infra` | Infra types routed to wisps table | -| `import.orphan_handling` | `allow` (default) \| `resurrect` \| `skip` \| `strict` | -| `compact_*` | Compaction tuning (see [docs/CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md)) | -| `issue_id_mode` | `hash` (default) \| `counter` (sequential) | -| `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `4` and `8`) | +| `types.infra` | Infra types routed to the wisps table instead of the versioned issues table | +| `compact_tier1_days`, `compact_tier2_days` | Age thresholds in days for `bd admin compact` tier eligibility (defaults `30` and `90`) | +| `issue_id_mode` | `hash` (default) \| `counter` (see [below](#sequential-counter-ids)) | +| `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `3` and `8`) | | `max_collision_prob` | Hash ID collision tolerance (default `0.25`) | -| `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug | +| `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug (warnings only; errors always show) | Issue prefix (`issue_prefix`) is **not** settable via `bd config set` β€” use `bd init --prefix`, `bd bootstrap`, or `bd rename-prefix`. +### Custom Statuses and Types + +Custom statuses supplement the built-ins (`open`, `in_progress`, `blocked`, `deferred`, `closed`). Each entry is `name` or `name:category`: + +```bash +bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done" +``` + +The category controls how the status behaves: + +| Category | In `bd ready` | In default `bd list` | +|---|---|---| +| `active` | yes | yes | +| `wip` | no | yes | +| `done` | no | no (terminal) | +| `frozen` | no | no (on hold) | +| (none) | no | yes (backward compatible) | + +Custom types extend the built-in issue types: + +```bash +bd config set types.custom "agent,molecule,event" +``` + +Use `bd statuses` and `bd types` to list everything configured. + +### Sequential Counter IDs + +By default, beads generates hash-based IDs (e.g. `bd-a3f2`). For projects that prefer short sequential IDs (`bd-1`, `bd-2`, ...), enable counter mode: + +```bash +bd config set issue_id_mode counter + +bd create "First issue" -p 1 # β†’ bd-1 +bd create "Second issue" -p 2 # β†’ bd-2 +``` + +| Value | Behavior | +|---|---| +| `hash` | (default) Hash-based IDs, adaptive length, collision-safe | +| `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, ... | + +Counter mode behavior: + +- Each prefix (`bd`, `plug`, ...) has its own independent counter, so multi-repo or routed setups don't interleave. +- The counter is stored atomically in the database; concurrent creates within a single Dolt session are safe. +- On first use (including switching an existing repository to counter mode), the counter seeds itself from the highest existing numeric ID for that prefix, so new IDs don't collide with old ones. +- An explicit `--id` flag on `bd create` bypasses ID generation entirely; the counter is not incremented. +- Counter mode applies only to regular issues, not wisps. + +Tradeoff β€” hash vs. counter: + +| | Hash IDs | Counter IDs | +|---|---|---| +| Human readability | Lower (`bd-a3f2`) | Higher (`bd-1`) | +| Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) | +| Predictability | Unpredictable | Sequential | +| Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs | + +### Adaptive Hash IDs + +Hash IDs size themselves to the database: lengths start at `min_hash_length` and grow toward `max_hash_length` to keep the collision probability under `max_collision_prob`. + +```bash +bd config set max_collision_prob "0.01" # Stricter collision tolerance (default 0.25) +bd config set min_hash_length "5" # Force minimum 5-char IDs (default 3) +bd config set max_hash_length "8" # Upper bound (default 8) +``` + +## Sync and Federation + +Beads syncs exclusively through Dolt remotes (`bd dolt push` / `bd dolt pull`) with cell-level merge. Use `bd export` for issue portability and `bd backup` for restorable database backups. + +Federation settings live in `config.yaml`: + +```yaml +federation: + remote: dolthub://myorg/beads + sovereignty: T2 +``` + +- `federation.remote`: Dolt remote URL (`dolthub://org/beads`, `gs://bucket/beads`, `s3://bucket/beads`, `az://account.blob.core.windows.net/container/beads`, `file://...`) +- `federation.sovereignty`: data sovereignty tier: + - `T1`: Full sovereignty β€” data never leaves controlled infrastructure + - `T2`: Regional sovereignty β€” data stays within region/jurisdiction + - `T3`: Provider sovereignty β€” data with trusted cloud provider + - `T4`: No restrictions β€” data can be anywhere + +`bd config validate` checks the remote URL format, the sovereignty tier, `federation.allowed-remote-patterns`, and `routing.mode`. + +## Integration Configuration + +Tracker settings are project-level config under the tracker's namespace; secrets (`jira.api_token`, `linear.api_key`, `github.token`, `gitlab.token`, `ado.pat`) are YAML-routed and better supplied as environment variables. Every tracker records `.last_sync` automatically after a sync, enabling incremental syncs. + +### Jira + +```bash +bd config set jira.url "https://company.atlassian.net" +bd config set jira.project "PROJ" +bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated) +export JIRA_API_TOKEN="YOUR_TOKEN" # or: bd config set jira.api_token ... + +# Map bd statuses to Jira statuses +bd config set jira.status_map.open "To Do" +bd config set jira.status_map.in_progress "In Progress" +bd config set jira.status_map.closed "Done" + +# Map bd issue types to Jira issue types +bd config set jira.type_map.bug "Bug" +bd config set jira.type_map.feature "Story" +bd config set jira.type_map.task "Task" + +# Set Jira custom fields on pushed issues +bd config set jira.custom_fields.customfield_10042 '{"value":"AI Platform"}' +bd config set jira.custom_fields.Story.customfield_10042 '{"value":"AI Platform"}' +``` + +`jira.custom_fields.` applies to every issue pushed to Jira. `jira.custom_fields..` applies only when the mapped Jira issue type matches ``; per-type fields override global fields with the same field key. Values beginning with `{` or `[` are sent as JSON (useful for select-like fields); other values are sent as strings. `jira.url`, `jira.project`/`jira.projects`, and `jira.api_token` fall back to the `JIRA_URL`, `JIRA_PROJECT`/`JIRA_PROJECTS`, and `JIRA_API_TOKEN` environment variables. See [bd jira](/cli-reference/jira). + +### Linear + +```bash +export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # Settings β†’ API β†’ Personal API keys + +bd config set linear.team_id "team-uuid-here" +bd config set linear.team_ids "uuid-1,uuid-2" # Multiple teams (or LINEAR_TEAM_IDS) +``` + +When `linear.team_ids` is set, `bd linear sync` fetches issues from all listed teams; push with multiple teams configured requires an explicit `--team`. The singular `linear.team_id` remains supported. + +Mapping namespaces β€” `linear.priority_map.*` (Linear 0–4 β†’ beads 0–4), `linear.state_map.*` (Linear state types and custom state names β†’ beads statuses, e.g. `bd config set linear.state_map.in_review in_progress`), `linear.label_type_map.*` (Linear labels β†’ bd issue types), and `linear.relation_map.*` (Linear relations β†’ bd dependencies; imported only when pulling with `--relations`) β€” are documented with defaults in [bd linear](/cli-reference/linear). + +Staleness detection: after each successful pull, `bd` writes a timestamp to `.beads/last_pull` (a local-only, per-machine file covered by the `.beads/.gitignore` template). `bd linear sync --pull-if-stale` pulls only when data is older than the threshold (`--threshold`, default 20m), and a 5-minute debounce prevents agent loops. `bd prime` and other core commands never contact Linear β€” run `bd linear sync --pull-if-stale` from a session-start hook to keep data fresh in agent sessions. + +### GitHub + +```bash +bd config set github.org "myorg" +bd config set github.repo "myrepo" +export GITHUB_TOKEN="YOUR_TOKEN" # or: bd config set github.token ... + +# Map bd labels to GitHub labels +bd config set github.label_map.bug "bug" +bd config set github.label_map.feature "enhancement" +``` + +See [bd github](/cli-reference/github). + +### Azure DevOps + +Connection keys (`ado.pat`, `ado.org`, `ado.project`, `ado.projects`, `ado.url`) each have an `AZURE_DEVOPS_*` environment variable equivalent; config keys take priority over env vars. When `ado.projects` is set, `bd ado sync` fetches work items from all listed projects in a single query. State maps default to the Agile process template (override with `ado.state_map.*` / `ado.type_map.*` for Scrum or CMMI), and priority mapping (ADO 1–4 ↔ beads 0–4, with backlog collapsing to low) is automatic and not configurable. Full setup, mapping tables, and sync commands: [Azure DevOps integration](/integrations/azure-devops) and [bd ado](/cli-reference/ado). + ## Environment Variables The Viper env prefix is `BD_`. Config keys map to env vars by upper-casing and replacing `.` and `-` with `_` (e.g. `dolt.auto-commit` β†’ `BD_DOLT_AUTO_COMMIT`, `validation.on-create` β†’ `BD_VALIDATION_ON_CREATE`). @@ -182,8 +444,9 @@ Selected commonly-used variables: | `BD_DB`, `BEADS_DB` | Database path (legacy `BEADS_DB` still honored) | | `BD_JSON` | Force JSON output | | `BD_DOLT_AUTO_COMMIT` | Override `dolt.auto-commit` (`on`/`off`) | -| `BD_DOLT_AUTO_PUSH` | Override `dolt.auto-push` | +| `BD_DOLT_AUTO_PUSH`, `BD_DOLT_AUTO_PUSH_INTERVAL`, `BD_DOLT_AUTO_PUSH_TIMEOUT` | Override auto-push settings | | `BD_BACKUP_ENABLED`, `BD_BACKUP_INTERVAL`, `BD_BACKUP_GIT_REPO` | Override backup settings | +| `BD_AGENT_PROFILE` | Override `agent.profile` | | `BD_AI_MODEL` | Override AI model | | `BD_FEDERATION_REMOTE`, `BD_FEDERATION_SOVEREIGNTY` | Override federation settings | | `BD_VALIDATION_ON_CREATE` / `_ON_CLOSE` / `_ON_SYNC` | Override validation modes | @@ -193,12 +456,19 @@ Selected commonly-used variables: | `BEADS_DIR` | Force the active beads workspace directory | | `BEADS_ACTOR` | Actor identity (preferred over `BD_ACTOR`, which is a deprecated alias) | | `BEADS_IDENTITY` | Sender identity for `bd mail` | +| `BEADS_FSCK_TIMEOUT` | Runtime-only timeout for the pre-push `dolt fsck --quiet` integrity check (default `30s`) | | `BEADS_DOLT_SERVER_MODE`, `BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_DATA_DIR`, `BEADS_DOLT_PORT`, ... | Embedded/server Dolt overrides | -Secrets like API tokens follow integration-specific conventions: `LINEAR_API_KEY`, `GITHUB_TOKEN`, `ANTHROPIC_API_KEY`, `AZURE_DEVOPS_PAT`. These are preferred over storing the value in `config.yaml` for git-tracked projects. +Integration secrets follow tracker-specific conventions: `LINEAR_API_KEY`, `GITHUB_TOKEN`, `GITLAB_TOKEN`, `JIRA_API_TOKEN`, `AZURE_DEVOPS_PAT`, `ANTHROPIC_API_KEY`. These are preferred over storing the value in `config.yaml` for git-tracked projects. `bd config show` will display the source of every effective key, making overrides explicit. +## Security: Where Secrets Live + +- Tokens and API keys are never stored in the Dolt database β€” database config is pushed to remotes, which would expose secrets and trip GitHub secret scanning. `bd config set` routes secret keys to the local `config.yaml` instead. +- Writing a secret to a git-tracked `config.yaml` is refused unless you pass `--force-git-tracked`; environment variables are the safer default. +- `bd init` writes a `.beads/.gitignore` that keeps the database directories (`embeddeddolt/`, `dolt/`), runtime files, push state, and the federation credential key out of git. + ## Example `.beads/config.yaml` ```yaml @@ -265,6 +535,18 @@ bd --db /tmp/test.db list # Override database for one command bd --json --actor "ci-bot" create "Fix things" # Multiple flags ``` +## Use in Scripts + +Configuration is designed for scripting; every `bd config` subcommand takes `--json`: + +```bash +# Get one value ({"key":"jira.url","value":"..."}) +JIRA_URL=$(bd config get --json jira.url | jq -r '.value') + +# Get all database config as a flat object +bd config list --json | jq -r '.["jira.project"]' +``` + ## Viewing Active Configuration ```bash diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 905e27286..15ad94a9b 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -1,113 +1,214 @@ --- title: FAQ +description: Common questions about beads and how to use it effectively --- ## General +### What is beads? + +Beads (`bd`) is a lightweight, Dolt-backed issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, so agents and humans can collaborate from the same task graph. See [Core Concepts](/core-concepts/index) for the full model. + ### Why beads instead of GitHub Issues or Jira? -Beads was designed specifically for AI-supervised coding workflows: -- **Hash-based IDs** prevent collisions with concurrent agents -- **Dolt-backed storage** enables branch-based workflows -- **Dependency-aware** ready queue for automated work selection -- **Formula system** for declarative workflow templates +GitHub Issues plus the `gh` CLI can approximate some features, but hosted trackers fundamentally cannot replicate what AI agents need: + +| Capability | beads | GitHub Issues | +|---|---|---| +| Typed dependencies | Four types (`blocks`, `related`, `parent-child`, `discovered-from`) with distinct behaviors | Only "blocks/blocked by" links; no semantic enforcement, no `discovered-from` for agent work discovery | +| Ready-work detection | `bd ready` computes transitive blocking offline in milliseconds | No built-in "ready" concept; requires custom GraphQL plus a sync service | +| Offline-first task memory | Works offline; issues live in a local, version-controlled database; hash IDs prevent collisions on merge | Cloud-first; requires network and auth; no branch-scoped task state | +| Conflicts and duplicates | Automatic collision resolution; duplicate merge with dependency consolidation and reference rewriting | Manual close-as-duplicate; no safe bulk merge, no cross-reference updates | +| Local SQL database | Full SQL queries against a local Dolt database with native version control | No local database; data must be mirrored externally | +| Agent-native APIs | Consistent `--json` on all commands; dedicated MCP server with workspace detection | Mixed JSON/text output; no agent-focused MCP layer | + +When to use each: GitHub Issues and Jira excel for human teams working in a web UI with cross-repo dashboards and integrations. Beads excels for AI agents that need offline, version-controlled task memory with graph semantics and deterministic queries. The two can also coexist β€” beads syncs bidirectionally with GitHub, Jira, and Linear (see [Migration](#migration)). + +### How is beads different from Taskwarrior? + +Taskwarrior is excellent for personal task management, but beads is built for AI agents: + +- **Agent semantics**: the `discovered-from` dependency type, `bd ready` for queue management +- **JSON-first design**: every command has `--json` output +- **Built-in sync**: version-controlled storage with native push/pull, no separate sync server to run +- **Cell-level merge**: concurrent changes merge automatically at the field level +- **SQL database**: full SQL queries against the Dolt database + +### Can I use beads without AI agents? + +Absolutely. Beads is a good CLI issue tracker for humans too β€” `bd ready` is useful for anyone managing dependencies. Think of it as "Taskwarrior meets git." ### What does "beads" stand for? -Nothing specific - it's a metaphor for linked work items (like beads on a string). +Nothing specific β€” it's a metaphor for linked work items, like beads on a string. ### Is beads production-ready? -Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning. +Beads is a 1.x product used in production for AI-assisted development. The core functionality β€” create, update, dependencies, ready work, Dolt-backed sync β€” is stable, and releases follow semantic versioning. Data stays portable: `bd export` produces human-readable JSONL, and `bd backup` pushes Dolt-native backups. As with any tracker holding work you care about, keep normal backup hygiene (a Dolt remote or a `bd backup` destination). ## Architecture -### Why Dolt instead of plain SQLite? +### Why Dolt instead of plain SQLite or flat files? -- **Dolt** provides a version-controlled SQL database with built-in replication -- Git-like branching, diffing, and merging at the database level -- No need for a separate sync format -- Dolt handles it natively +Dolt is a version-controlled SQL database β€” git semantics at the database level: + +- **Version-controlled SQL**: full SQL queries with branch, diff, and merge built in +- **Cell-level merge**: concurrent changes merge automatically at the field level +- **No separate sync format**: `bd dolt push` / `bd dolt pull` move history natively +- **Multi-writer**: server mode supports concurrent agents +- **Portable**: `bd export` produces JSONL for migration and interoperability + +See [Dolt architecture](/architecture/dolt) for the detailed analysis and [Storage backends](/architecture/storage-backends) for the alternatives. ### Why hash-based IDs instead of sequential? -Sequential IDs (`#1`, `#2`) break when: -- Multiple agents create issues simultaneously -- Different branches have independent numbering -- Forks diverge and merge +Sequential IDs (`#1`, `#2`) collide the moment two agents or two branches create issues concurrently β€” both mint the same next number, and the merge produces two different issues with one ID. Hash IDs like `bd-a1b2` are globally unique without coordination: -Hash-based IDs are globally unique without coordination. +```bash +# Branch A +bd create "Add OAuth" # bd-a1b2 -### How does the Dolt server work? +# Branch B +bd create "Add Stripe" # bd-f14c β€” no collision -Beads uses Dolt server mode for concurrent access: -- Transaction isolation for multiple agents -- SQL-based queries for performance -- Automatic retry on conflicts +git merge feature-auth # clean merge, distinct IDs +``` -In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required). +IDs start at 4 characters and automatically grow (5, then 6) as the database passes roughly 500 and 1,500 issues, keeping collision probability low. See [Hash IDs](/core-concepts/hash-ids) and [Adaptive IDs](/core-concepts/adaptive-ids), or the [collision math](https://github.com/gastownhall/beads/blob/main/engdocs/COLLISION_MATH.md) if you want the numbers. + +### What are hierarchical child IDs? + +Hierarchical IDs (`bd-a3f8e9.1`, `bd-a3f8e9.2`) give epics and their subtasks human-readable structure: + +```bash +bd create "Auth System" -t epic # bd-a3f8e9 +bd create "Login UI" --parent bd-a3f8e9 # bd-a3f8e9.1 +bd create "Validation" --parent bd-a3f8e9 # bd-a3f8e9.2 +``` + +The parent hash keeps the namespace unique across epics, the child numbers stay human-friendly, and up to 3 levels of nesting are supported. Use them for work breakdown structures; for cross-cutting relationships, use `bd dep add` instead. See [Hash IDs](/core-concepts/hash-ids). + +### Embedded mode or server mode β€” which am I running? + +The default `bd init` uses **embedded mode**: Dolt runs in-process inside `bd`, data lives at `.beads/embeddeddolt/`, and there is no server, port, or PID file to manage. This is the right mode for solo work, CI/CD, and single-agent setups. + +**Server mode** (`bd init --server`) connects to a running `dolt sql-server` and stores data at `.beads/dolt/`. Switch to it when multiple processes need concurrent write access to the same database β€” for example several agents on one machine. See [Dolt architecture](/architecture/dolt) for setup and migration between modes. ## Usage -### How do I sync issues? +### Should I run bd init myself or have my agent do it? + +Either works β€” use the right flag: ```bash -# Push changes to Dolt remote: -bd dolt push - -# Pull changes from Dolt remote: -bd dolt pull +bd init # Humans: interactive, prompts for git hooks +bd init --quiet # Agents: non-interactive, auto-installs hooks ``` +For an existing project, clone and run `bd init`; it creates the Dolt database and pulls from the configured remote. For a new project, run `bd init`, then commit the `.beads/` directory. + +### How do I sync issues across machines? + +```bash +bd dolt push # Push changes to the Dolt remote +bd dolt pull # Pull changes from the Dolt remote +``` + +`bd init` auto-configures your git origin as the Dolt remote when present; use `bd init --remote ` for an explicit remote. See [Sync Setup](/getting-started/sync-setup). + +### Do I need to run export/import manually? + +No. All writes go directly to the Dolt database and are committed to Dolt history automatically; `bd dolt push` / `bd dolt pull` handle sync. `bd export` exists for portability and interchange β€” `.beads/issues.jsonl` is a passive export, never the database. For backups, use `bd backup init ` / `bd backup sync` / `bd backup restore`. See [Sync Concepts](/core-concepts/sync-concepts) for the full model and the sync patterns to avoid. + +### What if my database feels stale after a colleague pushes changes? + +```bash +bd dolt pull # Fetch and merge updates from the Dolt remote +bd ready # Shows fresh data +``` + +For federation setups, `bd federation sync` syncs with all configured peers. See [Federation](/multi-agent/federation). + ### How do I handle merge conflicts? -Dolt handles merge conflicts at the database level. If conflicts arise during pull: +Dolt merges at the cell level, so most concurrent changes resolve automatically. Importing an issue with the same ID but different fields is an update, not a collision β€” hash IDs are stable, so same ID means same issue. If `bd dolt pull` does report conflicts: + ```bash bd doctor --fix bd dolt push ``` +See the [merge conflicts runbook](/recovery/merge-conflicts). + +### Can I track issues for multiple projects? + +Yes β€” each project is completely isolated: + +```bash +cd ~/project1 && bd init --prefix proj1 +cd ~/project2 && bd init --prefix proj2 +``` + +Each project gets its own `.beads/` directory and database, and `bd` auto-discovers the right one by walking up from your current directory (like git). Issues cannot reference issues in other projects; if you need cross-project tracking, initialize beads in a parent directory that contains both. + +In server mode, each project runs its own Dolt server by default. On machines with many projects you can opt into a single shared server (`bd init --shared-server`, or `export BEADS_DOLT_SHARED_SERVER=1`) that serves every project from `~/.beads/shared-server/`. See [Dolt architecture](/architecture/dolt). + ### Can multiple agents work on the same repo? -Yes! That's what beads was designed for: -- Hash IDs prevent collisions -- Pin work to specific agents -- Track who's working on what +Yes β€” that's what beads was designed for. Hash IDs prevent collisions, and assignment tracks who's working on what: + +```bash +bd ready --assignee agent-name # Query ready work for an agent +bd update bd-a1b2 --claim # Atomically claim an issue (assignee + in_progress) +bd create "Found issue" --deps discovered-from:bd-a1b2 # Track discovered work +``` + +In orchestrated workflows an orchestrator usually assigns work (`bd assign`); agents picking work directly should use the atomic `--claim`. For multiple concurrent processes on one machine, use server mode; for distributed setups, Dolt's cell-level merge and [federation](/multi-agent/federation) let agents work independently and merge like developers do. See [Agent Coordination](/multi-agent/coordination). + +### Does beads work offline? + +Yes β€” beads is offline-first. All queries run against the local Dolt database, no command needs the network, and sync happens via `bd dolt push` / `bd dolt pull` when you're online. That makes it suitable for planes, unstable connections, air-gapped environments, and privacy-sensitive projects. ### How do I use beads in CI/CD? +Just run commands β€” embedded mode is the default, so no server is required: + ```bash -# Just run commands directly β€” beads uses embedded mode in CI -bd list +bd list --json +bd ready --json ``` ## Workflows ### What are formulas? -Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances). +Declarative workflow templates in TOML or JSON. `bd cook` compiles a formula into a proto (a template epic), and `bd mol pour` instantiates the proto as a molecule of real, tracked beads. See [Formulas](/workflows/formulas). ### What are gates? -Async coordination primitives: -- Human gates wait for approval -- Timer gates wait for duration -- GitHub gates wait for CI/PR events +Async coordination primitives that block a workflow step until a condition clears: + +- **Human gates** wait for approval +- **Timer gates** wait for a duration +- **GitHub gates** wait for CI runs or PR events + +See [Gates](/workflows/gates). ### What's the difference between molecules and wisps? -- **Molecules** persist in `.beads/` and sync with git -- **Wisps** are ephemeral in `.beads-wisp/` and don't sync +Both are instantiated workflows made of real beads. **Molecules** (`bd mol pour`) are persistent β€” part of history, synced like any bead. **Wisps** (`bd mol wisp`) are ephemeral β€” flagged so they stay out of federation push and can be deleted wholesale (`bd purge`, `bd mol wisp gc`) once closed. Use molecules for work worth referencing later, wisps for operational loops like release checklists and health patrols. See [Molecules](/workflows/molecules) and [Wisps](/workflows/wisps). -## Integration +## Integrations -### Should I use CLI or MCP? +### Should I use the CLI or MCP? -**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.): -- Lower context overhead (~1-2k vs 10-50k tokens) +**Use CLI + hooks** when a shell is available (Claude Code, Cursor, and similar): + +- Lower context overhead (roughly 1-2k tokens vs 10-50k for MCP tool schemas) - Faster execution - Universal across editors -**Use MCP** when CLI unavailable (Claude Desktop). +**Use MCP** when the CLI is unavailable (for example Claude Desktop). See [MCP Server](/integrations/mcp-server). ### How do I integrate with my editor? @@ -117,38 +218,148 @@ bd setup cursor # Cursor bd setup aider # Aider ``` +`bd setup` also supports copilot, gemini, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. See [IDE Setup](/getting-started/ide-setup) and the [integrations index](/integrations/index). + ### Can beads import from GitHub Issues? -Yes β€” see the [GitHub integration documentation](https://github.com/gastownhall/beads/blob/main/docs/GITHUB_IMPORT.md) for details. +Yes β€” `bd github pull` imports issues and `bd github sync` keeps beads and GitHub in sync bidirectionally. See the [bd github reference](/cli-reference/github). + +## Migration + +### How do I migrate from GitHub Issues, Jira, or Linear? + +Beads has built-in bidirectional sync for all three β€” `bd github`, `bd jira`, and `bd linear` each provide `pull`, `push`, and `sync` (GitLab, Azure DevOps, and Notion are covered by `bd gitlab`, `bd ado`, and `bd notion`). Configure credentials with `bd config set` per the [CLI reference](/cli-reference/index), then pull. + +For any other tracker: export from it (usually CSV or JSON), convert to beads' JSONL format, and run `bd import `. See [examples](https://github.com/gastownhall/beads/tree/main/examples) for scripting patterns. + +### Can I export back out of beads? + +For GitHub, Jira, and Linear, use the same integrations in the push direction (`bd github push`, `bd jira push`, `bd linear push`). For anything else, `bd export -o issues.jsonl` produces JSONL you can convert with a script and feed to the target system's API. + +## Performance + +### How does beads handle scale? + +Dolt handles millions of rows efficiently. For a typical project with thousands of issues, commands complete in under 100ms, search is instant, and dependency graphs traverse quickly. For extremely large projects (100k+ issues), consider splitting into multiple databases per component. + +### What if my database gets too large? + +`bd gc` runs the full lifecycle: deletes old closed issues, squashes old Dolt commits, and runs Dolt garbage collection to reclaim disk space. + +```bash +bd gc --dry-run # Preview all phases +bd gc # Delete issues closed 90+ days ago, compact, GC +bd gc --older-than 30 # More aggressive decay window +``` + +For semantic summarization of old closed issues instead of deletion, see `bd admin compact`. Or split the project: + +```bash +cd ~/project/frontend && bd init --prefix fe +cd ~/project/backend && bd init --prefix be +``` + +## Use Cases + +### Can I use beads for non-code projects? + +Sure β€” beads is just an issue tracker. Writing projects (chapters as issues, outlines as dependencies), research (papers, experiments), home projects (renovations with blocking tasks) β€” any workflow with dependencies works, and the agent-friendly design fits any AI-assisted workflow. + +## Technical + +### What dependencies does beads have? + +Beads is a single static binary with no runtime dependencies β€” the Dolt engine is embedded in-process. No PostgreSQL, no Redis, no Docker, no node_modules. The standalone `dolt` CLI is only needed if you run server mode, and git is only needed to version your project code. See [Installation](/getting-started/installation). + +### Can I query or extend the database directly? + +Yes, three ways: `bd query` for the built-in query language (compound filters, boolean operators, date expressions), `bd sql` for raw SQL against the underlying database, and `--json` output on every command for building integrations. + +### Does beads support Windows? + +Yes β€” native Windows support, no MSYS or MinGW required. A PowerShell script installs prebuilt releases, and everything works with Windows paths. See [Installation](/getting-started/installation#windows-11). + +### Can I use beads with git worktrees? + +Yes β€” beads works from normal git worktrees with no special setup. All worktrees in a repository share the same `.beads` workspace; `bd` discovers it from linked worktrees automatically. + +If an old beads version left hidden worktrees under `.git/` (from a since-removed sync-branch feature), clean them up: + +```bash +rm -rf .git/beads-worktrees +rm -rf .git/worktrees/beads-* +git worktree prune +``` + +See [Worktrees](/reference/worktrees) for details and legacy cleanup. ## Troubleshooting ### Why is the Dolt server not starting? +This applies to server mode only (embedded mode has no server): + ```bash -# Check server status -bd doctor - -# Check server logs -cat .beads/dolt/sql-server.log - -# Restart the server -bd dolt stop -bd dolt start +bd doctor # Check health +cat .beads/dolt/sql-server.log # Check server logs +bd dolt stop && bd dolt start # Restart the server ``` +See [Troubleshooting](/reference/troubleshooting). + ### Why aren't my changes syncing? ```bash -# Force push to Dolt remote -bd dolt push - -# Check hooks -bd hooks status +bd dolt push # Push to the Dolt remote +bd hooks list # Verify git hooks are installed +bd doctor # Check for deeper issues ``` +See the [sync failures runbook](/recovery/sync-failures). + +### What's the difference between database corruption and ID collisions? + +These are two distinct integrity issues: + +**Logical consistency** β€” same ID assigned to different issues, wrong-prefix bugs, branch divergence. Hash-based IDs eliminate collisions by design, and `bd doctor --fix` repairs logical inconsistencies. + +**Physical corruption** β€” disk failures, power loss, or multiple processes writing to an embedded database simultaneously. Start with the [database corruption runbook](/recovery/database-corruption) (`bd doctor --fix` after backing up `.beads/`). If the database is unrecoverable and you have a Dolt remote, back up `.beads/`, delete the data directory for your mode β€” `.beads/embeddeddolt/` in embedded mode, `.beads/dolt/` in server mode β€” then re-init and pull: + +```bash +cp -r .beads .beads.backup +rm -rf .beads/embeddeddolt # or .beads/dolt in server mode +bd init +bd dolt pull +``` + +For multi-writer scenarios, use server mode so concurrent access goes through the server instead of racing on files. + ### How do I report a bug? 1. Check existing issues: https://github.com/gastownhall/beads/issues -2. Include: `bd version`, `bd info --json`, reproduction steps +2. Include `bd version`, `bd info --json`, and reproduction steps 3. File at: https://github.com/gastownhall/beads/issues/new + +## Getting Help + +### Where can I get more help? + +- **Documentation**: [Quickstart](/getting-started/quickstart), [Advanced Features](/reference/advanced), [README](https://github.com/gastownhall/beads/blob/main/README.md) +- **Troubleshooting**: [Troubleshooting guide](/reference/troubleshooting) and the [recovery runbooks](/recovery/index) +- **Examples**: [examples/](https://github.com/gastownhall/beads/tree/main/examples) +- **GitHub Issues**: [Report bugs or request features](https://github.com/gastownhall/beads/issues) +- **GitHub Discussions**: [Ask questions](https://github.com/gastownhall/beads/discussions) + +### How can I contribute? + +Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gastownhall/beads/blob/main/CONTRIBUTING.md) for guidelines, test instructions, and the development workflow. + +### Where's the roadmap? + +The roadmap lives in beads itself: + +```bash +bd list --priority-max 1 --json # All P0 and P1 issues +``` + +Or check GitHub Issues for feature requests and planned improvements. diff --git a/docs/reference/git-integration.md b/docs/reference/git-integration.md index 3032780c4..0f2980b3c 100644 --- a/docs/reference/git-integration.md +++ b/docs/reference/git-integration.md @@ -10,7 +10,9 @@ Beads uses git for: - **Project hosting** - Your code repository also hosts beads configuration - **Hooks** - Auto-sync on git operations -Data storage and sync are handled by Dolt (a version-controlled SQL database). +Data storage and sync are handled by Dolt (a version-controlled SQL database) β€” +see [Sync Concepts](/core-concepts/sync-concepts) for how issue data moves +between machines. ## File Structure @@ -18,26 +20,55 @@ Data storage and sync are handled by Dolt (a version-controlled SQL database). .beads/ β”œβ”€β”€ config.yaml # Project config (git-tracked) β”œβ”€β”€ metadata.json # Backend metadata (git-tracked) -└── dolt/ # Dolt database and server data (gitignored) +β”œβ”€β”€ .gitignore # Written by bd init (git-tracked) +β”œβ”€β”€ embeddeddolt/ # Dolt database β€” embedded mode, the default (gitignored) +└── dolt/ # Dolt database β€” server mode (gitignored) ``` +`bd init` writes `.beads/.gitignore` to keep the database directory and +runtime files out of git β€” no manual gitignore rules are needed. Never track +the database directory (`.beads/embeddeddolt/` or `.beads/dolt/`) in git or +via Git LFS. + ## Git Hooks ### Installation +`bd init` installs hooks by default (skip with `bd init --skip-hooks`). To +install or refresh them manually: + ```bash bd hooks install ``` -Installs: -- **pre-commit** - Triggers Dolt commit -- **post-merge** - Triggers Dolt sync after pull -- **pre-push** - Ensures Dolt sync before push +Installed hooks are thin shims that call `bd hooks run `, so +upgrading `bd` automatically updates hook behavior: + +| Hook | What it does | +|------|--------------| +| `pre-commit` | Runs chained hooks; when `export.auto` is enabled, exports `.beads/issues.jsonl` so it lands in the same commit | +| `post-merge` | Runs chained hooks; imports JSONL only as a legacy fallback when no Dolt remote is configured β€” with `sync.remote` set, `bd dolt pull` is the canonical sync | +| `pre-push` | Runs chained hooks before push | +| `post-checkout` | Runs chained hooks after branch checkout | +| `prepare-commit-msg` | Adds an `Executed-By:` agent identity trailer when an agent (`BD_ACTOR`) makes the commit | + +The shims use section markers to coexist with existing hooks β€” content +outside the markers is preserved across installs and upgrades. Install +variants: + +```bash +bd hooks install --beads # Install to .beads/hooks/ (recommended for the Dolt backend) +bd hooks install --shared # Install to .beads-hooks/ (versioned, shareable with the team) +bd hooks install --chain # Run existing hooks before bd hooks +``` + +Hook installation is worktree-aware: `bd` resolves the shared git directory, +so installing from a linked worktree works. ### Status ```bash -bd hooks status +bd hooks list ``` ### Uninstall @@ -46,6 +77,70 @@ bd hooks status bd hooks uninstall ``` +### External Hook Managers + +bd detects these external git hook managers and checks whether their config +calls `bd hooks run`: + +- [lefthook](https://lefthook.dev/) β€” YAML/TOML/JSON config +- [husky](https://typicode.github.io/husky/) β€” `.husky/` directory scripts +- [pre-commit](https://pre-commit.com/) β€” `.pre-commit-config.yaml` +- [prek](https://prek.j178.dev/) β€” Rust-based pre-commit alternative (same config) +- [hk](https://hk.jdx.dev/) β€” fast hook manager using Pkl config +- [overcommit](https://github.com/sds/overcommit) β€” Ruby-based (detection only) +- yorkie β€” detection only +- [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks) β€” lightweight JS (detection only) + +`bd doctor` reports whether a detected manager is integrated with bd, and +`bd doctor --fix` reinstalls the hooks with `--chain` so the manager's +existing hooks keep running. + +For config-driven managers, add bd steps directly. Example `hk.pkl`: + +```pkl +hooks { + ["pre-commit"] { + steps { + ["bd-pre-commit"] { + check = "bd hooks run pre-commit" + } + } + } + ["post-merge"] { + steps { + ["bd-post-merge"] { + check = "bd hooks run post-merge" + } + } + } + ["pre-push"] { + steps { + ["bd-pre-push"] { + check = "bd hooks run pre-push \"$@\"" + } + } + } +} +``` + +### Hook Timeout + +The hook shim wraps `bd hooks run` with an OS-level `timeout` so hooks cannot +hang git operations indefinitely. The default is **300 seconds** (5 minutes), +which accommodates chained pre-commit pipelines (eslint, prettier, TypeScript +compilation). Override it with the `BEADS_HOOK_TIMEOUT` environment variable: + +```bash +# Set a longer timeout (in seconds) +export BEADS_HOOK_TIMEOUT=600 # 10 minutes + +# Or set it per-invocation +BEADS_HOOK_TIMEOUT=600 git commit -m "..." +``` + +When the timeout is reached, beads prints a warning and lets the git +operation proceed β€” the commit or push is not blocked. + ## Conflict Resolution Dolt handles merge conflicts at the database level using its built-in @@ -65,6 +160,9 @@ beads data does not conflict with protected Git branches, and no separate with a Git `origin`, `bd init` configures that origin as the Dolt remote automatically. +See [Protected Branches](/reference/protected-branches) for the full +workflow, including legacy `beads-sync` cleanup. + ## Git Worktrees Beads works in Git worktrees without extra setup. Linked worktrees discover the @@ -78,6 +176,14 @@ bd dolt pull bd dolt push ``` +All worktrees share the repository's `.beads` workspace: discovery follows +`BEADS_DIR` if set, then the main repository's `.beads`, preventing database +duplication across worktrees. Use `bd where` as the authoritative check for +which workspace is active β€” a local `./.beads` may legitimately be absent in +a worktree. Embedded mode (the default) serves one writer at a time; for +concurrent writers across worktrees, use server mode. See +[Git Worktrees](/reference/worktrees) for the full guide. + Older beads versions documented a `sync.branch` workflow that created hidden Git worktrees. That workflow has been removed; current sync uses Dolt remotes. @@ -97,11 +203,20 @@ git push ```bash # In fork -bd init --contributor +bd init --contributor # Interactive wizard # Work in separate planning repo... bd dolt push ``` +The contributor wizard keeps issue data in a separate planning repository, +leaving the upstream repo without any `.beads/`. Best for open source +contributors, solo developers, and private task tracking on public repos. + +`bd init` auto-detects forks and offers to configure `.git/info/exclude` +(`--setup-exclude`) so beads files stay local. Set the role without prompting +via `--role contributor` or `--role maintainer` (the default in +non-interactive mode). + ### Team Workflow ```bash @@ -111,6 +226,10 @@ bd dolt pull # Pull latest changes from Dolt remote bd dolt push # Push your changes to Dolt remote ``` +Best for teams on protected branches and review-before-merge policies. See +[Multi-Repo Migration](/multi-agent/multi-repo-migration) for multi-repo +patterns. + ### Duplicate Detection After merging branches: @@ -119,6 +238,60 @@ After merging branches: bd duplicates --auto-merge ``` +## Branchless Workflows (Jujutsu / jj) + +Beads works with branchless VCS tools like +[Jujutsu (jj)](https://martinvonz.github.io/jj/). Since beads data is stored +in Dolt (not git branches), there is no dependency on the "current branch" +concept. + +### What Works Without Hooks + +All core beads functionality works without git hooks: + +| Feature | Hooks Required? | Notes | +|---------|----------------|-------| +| `bd create`, `bd update`, `bd close` | No | Core CRUD uses Dolt directly | +| `bd ready`, `bd list`, `bd show` | No | Read-only queries | +| `bd dolt push` / `bd dolt pull` | No | Dolt-native sync, independent of git | +| `bd onboard`, `bd doctor` | No | Diagnostics and onboarding | +| Agent identity trailers | Yes | `prepare-commit-msg` hook adds `Executed-By:` to commits | +| Hook chaining | Yes | Preserves existing pre-commit, post-merge hooks | + +To skip hooks entirely during init: + +```bash +bd init --skip-hooks +``` + +### What Works Without AGENTS.md + +The AGENTS.md file generated by `bd init` provides AI agent instructions. If +you manage your own agent instructions or don't want beads to modify tracked +files: + +```bash +bd init --skip-agents # Skip AGENTS.md and Claude/Codex setup generation +bd init --stealth # Full invisible mode (also skips hooks + agents) +``` + +### Jujutsu Setup + +**Colocated repos** (`jj git init --colocate`): Git hooks work normally. +Beads installs simplified hooks (`pre-commit` and `post-merge` only, no +staging logic). + +**Pure jj repos** (no git): Since jj doesn't have native hooks yet, set up +push aliases: + +```toml +# ~/.config/jj/config.toml +[aliases] +push = ["util", "exec", "--", "sh", "-c", "bd dolt commit && bd dolt push && jj git push \"$@\"", ""] +``` + +Then use `jj push` instead of `jj git push`. + ## Best Practices 1. **Install hooks** - `bd hooks install` diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index b26419053..1cfd663b6 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -2,7 +2,8 @@ title: Troubleshooting --- -Common issues and solutions. +Common issues and solutions. For step-by-step runbooks, see the +[Recovery section](/recovery/index). ## Installation Issues @@ -13,27 +14,79 @@ Common issues and solutions. which bd go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd -# Add Go bin to PATH +# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" # Or reinstall with the recommended installer curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` +### Wrong version of bd running + +If `bd version` shows an unexpected version (e.g., older than what you just +installed), you likely have multiple `bd` binaries in your PATH: + +```bash +# Check all bd binaries in PATH +which -a bd + +# Example output showing conflict: +# /Users/you/go/bin/bd <- From go install (older) +# /opt/homebrew/bin/bd <- From Homebrew (newer) + +# Remove the old go install version +rm ~/go/bin/bd + +# Or remove mise-managed Go installs +rm ~/.local/share/mise/installs/go/*/bin/bd + +# Verify +which bd +bd version +``` + +This happens when a binary from an earlier `go install` sits in `~/go/bin/` +ahead of a newer package-manager install. Choose one installation method +(Homebrew recommended) and stick with it. + ### `zsh: killed bd` on macOS CGO/SQLite compatibility issue: ```bash CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest + +# Or if building from source +git clone https://github.com/gastownhall/beads +cd beads +CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd +sudo mv bd /usr/local/bin/ ``` +Homebrew builds already enable CGO, so this shouldn't be necessary there. If +you still see crashes with the Homebrew version, please +[file an issue](https://github.com/gastownhall/beads/issues). + ### Permission denied ```bash chmod +x $(which bd) + +# Or install to a user directory instead +mkdir -p ~/.local/bin +mv bd ~/.local/bin/ +export PATH="$HOME/.local/bin:$PATH" ``` +### Antivirus flags bd as malware + +Kaspersky, Windows Defender, and others sometimes flag `bd` as a generic +trojan. This is a **false positive** β€” Go binaries commonly trigger antivirus +heuristics. Verify the binary's SHA256 checksum against the +[GitHub release page](https://github.com/gastownhall/beads/releases) before +adding an exclusion. See [Antivirus False Positives](/reference/antivirus) for +per-vendor instructions. + ## Database Issues ### Database not found @@ -42,33 +95,272 @@ chmod +x $(which bd) # Initialize beads bd init --quiet -# Or specify database -bd --db .beads/beads.db list +# Or point bd at an existing .beads directory +BEADS_DIR=/path/to/.beads bd list ``` ### Database locked ```bash -# Stop the Dolt server if running +# Stop the Dolt server if running (server mode) bd dolt stop +# Find and kill hanging bd processes +ps aux | grep bd +kill + # Try again bd list ``` + +Do NOT remove files inside `.dolt/` directories (including `noms/LOCK`). +These are Dolt-internal files β€” removing them WILL cause unrecoverable data +corruption. Dolt manages these files itself. + + +For high-concurrency scenarios (multiple agents), server mode +(`bd init --server`) handles concurrent access natively via `dolt sql-server`. + +### `bd init` refuses to run + +`bd init` and `bd dolt` refuse operations that could destroy local or remote +history, printing a pattern code such as `init-local-exists` or +`pk-fork-refused`. Each code has a runbook β€” see +[Recovery Playbooks](/recovery/init-safety). Export first +(`bd export -o backup.jsonl`) if you intend to re-initialize over existing +data. + ### Corrupted database +Distinguish **logical consistency issues** (ID collisions, wrong prefixes) +from **physical database corruption** (disk failures, power loss, filesystem +errors). + +For logical consistency issues β€” this is not corruption: + ```bash -# Check and fix database bd doctor --fix - -# Or pull from Dolt remote -bd dolt pull - -# Or restore from a backup -bd backup restore [path] --force ``` +For physical corruption, rebuild from a Dolt remote or a backup: + +```bash +# Move the damaged data directory aside: +mv .beads/embeddeddolt .beads/embeddeddolt.backup # embedded mode (default) +mv .beads/dolt .beads/dolt.backup # server mode + +bd init +bd dolt pull # Pull from Dolt remote if configured + +# Or restore from a backup: +# bd backup restore [path] --force +``` + +See [Database Corruption](/recovery/database-corruption) for the full runbook. + +### Dolt journal corruption after restart + +**Symptom (server mode):** After a system restart, `bd` reports that the Dolt +server started but is not accepting connections, and `.beads/dolt-server.log` +contains: + +```text +possible data loss detected in journal file at offset ...: corrupted journal +``` + +**Cause:** Dolt detected damaged journal blocks after an unclean shutdown. +This is not the same as a stale PID, stale port, or stale lock file. `bd` +will not run Dolt's data-loss repair mode automatically. + +**Safe recovery when your remote is current:** + +```bash +# Server mode data lives at .beads/dolt; embedded mode at .beads/embeddeddolt +mv .beads/dolt .beads/dolt.corrupt.$(date +%Y%m%dT%H%M%S) +bd bootstrap --dry-run +bd bootstrap --yes +bd stats +``` + +If the remote may be stale, keep the corrupt directory for forensics and +inspect it with `dolt fsck` before considering +`dolt fsck --revive-journal-with-data-loss`. Only use the revive path after +reviewing Dolt's data-loss warning. + +### `failed to import: issue already exists` + +You're trying to bootstrap a database with issues that conflict with existing +ones. Clear the local database and re-initialize from an export: + +```bash +# DESTROYS the local database β€” export first if unsure +rm -rf .beads/embeddeddolt # embedded mode (default) +rm -rf .beads/dolt # server mode + +bd init --from-jsonl +``` + +### Import fails with missing parent errors + +Errors like `parent issue bd-abc does not exist` when bootstrapping from JSONL +or pulling hierarchical issues (e.g., `bd-abc.1`) mean the parent issue was +deleted but children still reference it β€” typically after `bd delete` on a +parent, a branch merge where one side deleted it, or an incomplete import. + +Imports accept orphans without validation by default, so the children still +arrive; the error indicates the parent itself is gone. Recreate the parent +(or close out the orphaned children) after the import. + +**Prevention:** use `bd delete --cascade` to also delete children, and review +children first with `bd children `. + +### Old data returns after reset + +`bd admin reset --force` only removes **local** beads data. Old issues can +return from configured Dolt remotes or from other machines that push after +you reset. For a complete clean slate, reset every clone (or clear the +remote's beads data) before re-running `bd init`. + +If you previously used the removed legacy sync-branch feature, also delete +its branch and worktrees β€” see +[Worktrees: Legacy Cleanup](/reference/worktrees#legacy-cleanup). + +### `bd` shows 0 issues but the database has data + +**Symptom (server mode):** All `bd` commands return empty results even though +your data exists. + +**Cause:** `bd` is connecting to a different Dolt server or database than +expected β€” an empty "shadow" database on the wrong server. + +**Diagnosis:** + +```bash +# Check what mode and server bd is using +cat .beads/metadata.json | grep -E "dolt_mode|dolt_server_port" + +# Run server-mode health checks +bd doctor --server + +# Confirm what the connected database contains +bd sql 'SELECT COUNT(*) FROM issues' +``` + +**Fix:** ensure your Dolt server is running from the correct data directory +and that `metadata.json` points at the right server and port. If a stale +`.beads/dolt/` directory exists alongside an external-server configuration, +it can shadow the real database β€” confirm your real data lives on the server +before removing the stale directory. + +### Configured server unreachable (auto-start disabled) + +**Symptom (server mode):** `bd` returns "database not found on Dolt server" +when the configured server is down. + +**Cause:** When `metadata.json` has an explicit `dolt_server_port`, bd treats +the server as externally managed and intentionally disables auto-start β€” +spawning a different server would create a shadow database. + +**Fix:** + +```bash +# Start your configured Dolt server +bd dolt start + +# Or start manually with the correct data directory +dolt sql-server --host 127.0.0.1 --port 3307 --data-dir /path/to/your/dolt/data +``` + +If you want auto-start behavior, remove `dolt_server_port` from +`.beads/metadata.json`. + +### Port conflicts with multiple projects + +**Symptom (server mode):** Commands in a second project fail or connect to the +wrong database, and multiple `dolt sql-server` processes are running. + +**Cause:** Each server-mode project starts its own Dolt server by default, +which can conflict on machines with many projects. + +**Fix:** Enable shared server mode so all projects use a single Dolt server: + +```bash +# Option 1: Machine-wide (add to ~/.bashrc or ~/.zshrc) +export BEADS_DOLT_SHARED_SERVER=1 + +# Option 2: Per-project +bd config set dolt.shared-server true +``` + +After enabling, existing projects may need `bd init --reinit-local -q` to +create their database on the shared server. + +**Verify:** `bd dolt status` from any project should show the same server, +port 3308, and `~/.beads/shared-server/` as the data directory. + +### Multiple databases detected warning + +bd warns when it finds more than one `.beads` directory in your directory +hierarchy, marking the one in use with `β–Ά` (usually the closest to your +current directory). Multiple databases risk working in the wrong one or +tracking the same work twice. + +- **Nested projects (intentional):** this is supported β€” just note which + database is active, or pin it explicitly. +- **Accidental duplicates:** export from the unwanted database + (`bd export -o issue-export.jsonl`), then remove its `.beads` directory. +- **Override selection:** + + ```bash + # Point bd at a specific .beads directory (recommended) + export BEADS_DIR=/path/to/.beads + + # Legacy method (deprecated, points at the database file directly) + export BEADS_DB=/path/to/db + ``` + +### Circuit breaker: "server appears down, failing fast" + +**Symptom (server mode):** Every `bd` command fails with +`dolt circuit breaker is open: server appears down, failing fast (cooldown 30s)`, +persisting across repeated invocations. + +**Cause:** The circuit breaker tripped after repeated connection failures. +Its state lives in a file under `/tmp/beads-circuit/` (named +`beads-dolt-circuit--[-].json`, keyed on host:port) and is +shared across all `bd` processes. Once tripped, all commands to that host:port +are rejected until a successful probe resets it. + +For beads-managed local servers, `bd dolt status` reports from the server's +PID file β€” a "running" status does not guarantee the server is actually +accepting connections on the expected port. + +**Diagnosis:** + +```bash +# Check circuit breaker state +cat /tmp/beads-circuit/beads-dolt-circuit-*.json + +# Check if the Dolt server is actually listening +lsof -i : + +# Compare the configured port with what's running +cat .beads/metadata.json | grep port +``` + +**Fix:** + +```bash +rm /tmp/beads-circuit/beads-dolt-circuit-*.json +bd dolt stop +bd dolt start +bd list +``` + +On macOS, `/tmp` is a symlink to `/private/tmp`, which is not always cleared +on restart β€” the state file can persist across reboots. + ## Dolt Server Issues ### Server not starting @@ -77,8 +369,8 @@ bd backup restore [path] --force # Check server health bd doctor -# Check server logs -cat .beads/dolt/sql-server.log +# Check server logs (server mode; embedded mode runs in-process, no server log) +cat .beads/dolt-server.log # Restart the server bd dolt stop @@ -103,7 +395,7 @@ bd dolt start bd dolt push # Check hooks -bd hooks status +bd hooks list ``` ### Recovery from backup @@ -118,6 +410,10 @@ bd dolt pull ### Merge conflicts +Dolt merges at the cell level, so concurrent changes conflict only when they +touch the same field of the same issue. Hash-based IDs mean different issues +never collide on ID. + ```bash # Check for and fix Dolt conflicts bd doctor --fix @@ -126,6 +422,8 @@ bd doctor --fix bd dolt push ``` +See [Merge Conflicts](/recovery/merge-conflicts) for the full runbook. + ## Git Hook Issues ### Hooks not running @@ -148,10 +446,98 @@ cat .git/hooks/pre-commit .git/hooks/pre-commit ``` +### Hook timeout kills chained pre-commit hooks + +**Symptom:** After `bd hooks install`, chained pre-commit hooks (eslint, +prettier, ruff, etc.) stop running, with: +`beads: hook 'pre-commit' timed out after 300s -- continuing without beads`. + +**Cause:** The beads hook shim wraps `bd hooks run` with an OS-level timeout. +Since `bd hooks run` chains to your original hook internally, the timeout +covers both beads' own work and your entire hook pipeline. + +**Fix:** Increase the timeout (default 300 seconds): + +```bash +# Add to ~/.bashrc or ~/.zshrc +export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds) +``` + +### Permission denied on git hooks + +Git hooks need execute permissions: + +```bash +chmod +x .git/hooks/pre-commit +chmod +x .git/hooks/post-merge +chmod +x .git/hooks/post-checkout +``` + +### Corrupted symlinked `CLAUDE.md` + +**Symptom:** Git reports `CLAUDE.md` as a symlink entry (mode `120000`), but +the indexed blob contains multi-line Markdown instead of a one-line symlink +target. On macOS this can make clones or checkouts fail. + +This affects repositories corrupted by older setup behavior (fixed in +[#4192](https://github.com/gastownhall/beads/pull/4192)). To repair an +existing bad index entry: + +```bash +# Confirm the bad entry: mode 120000 but Markdown content +git ls-files -s CLAUDE.md +git cat-file -p :CLAUDE.md | sed -n '1,5p' + +# Convert the blob to a regular tracked file without changing content +sha=$(git rev-parse :CLAUDE.md) +git update-index --cacheinfo 100644,$sha,CLAUDE.md +git checkout-index -f -- CLAUDE.md + +# Verify: first column should now be 100644 +git ls-files -s CLAUDE.md +git diff -- CLAUDE.md +``` + +Commit the mode repair after review. + +### "Branch already checked out" or unexpected `.git/beads-worktrees/` + +Older beads versions created hidden git worktrees for a removed sync-branch +feature; leftovers can lock branches (`fatal: 'main' is already checked out +at .../beads-worktrees/...`). Remove them: + +```bash +rm -rf .git/beads-worktrees +rm -rf .git/worktrees/beads-* +git worktree prune +``` + +See [Worktrees: Legacy Cleanup](/reference/worktrees#legacy-cleanup). + ## Dependency Issues +### `bd ready` shows nothing but I have open issues + +Those issues probably have open blockers: + +```bash +# See blocked issues +bd blocked + +# Show the dependency tree (default max depth: 50) +bd dep tree +bd dep tree --max-depth 10 + +# Remove a blocking dependency if needed +bd dep remove +``` + +Remember: only `blocks` dependencies affect ready work. + ### Circular dependencies +bd prevents dependency cycles, which break ready work detection: + ```bash # Detect cycles bd dep cycles @@ -160,35 +546,212 @@ bd dep cycles bd dep remove bd-A bd-B ``` -### Missing dependencies +See [Circular Dependencies](/recovery/circular-dependencies) for the full +runbook. + +### Dependencies not showing up ```bash -# Check orphan handling -bd config get import.orphan_handling +# Show full issue details including dependencies +bd show -# Allow orphans -bd config set import.orphan_handling allow +# Visualize the dependency tree +bd dep tree ``` +Different dependency types have different meanings β€” only `blocks` gates +ready work. See [Dependencies](/core-concepts/dependencies). + ## Performance Issues ### Slow queries ```bash -# Check database size -ls -lh .beads/beads.db +# Check database stats +bd stats + +# Check on-disk size +du -sh .beads/embeddeddolt # embedded mode (default) +du -sh .beads/dolt # server mode + +# Preview compaction candidates +bd admin compact --dry-run --all # Compact if large bd admin compact --analyze ``` +Consider splitting very large projects into multiple databases: + +```bash +cd ~/project/component1 && bd init --prefix comp1 +cd ~/project/component2 && bd init --prefix comp2 +``` + ### High memory usage ```bash -# Reduce cache -bd config set database.cache_size 1000 +# Run Dolt garbage collection to compact storage +bd admin compact --dolt ``` +## Agent Issues + +### Agent creates duplicate issues + +Agents may not realize an issue already exists. Prevention strategies: + +- Have agents search first: `bd list --json | grep "title"` +- Label auto-created issues: `bd create "..." -l auto-generated` +- Consolidate duplicates: `bd duplicate --of ` closes + the duplicate with a reference to the canonical issue + +### Agent gets confused by complex dependencies + +Simplify the dependency structure: + +```bash +# Check for overly complex trees +bd dep tree + +# Remove unnecessary dependencies +bd dep remove + +# Use labels instead of dependencies for loose relationships +bd label add related-to-feature-X +``` + +### MCP server not working + +```bash +# Verify the MCP server is installed +pip list | grep beads-mcp + +# Check MCP configuration (Claude Desktop on macOS) +cat ~/Library/Application\ Support/Claude/claude_desktop_config.json + +# Test that the CLI itself works +bd version +bd ready +bd doctor +``` + +See [MCP Server](/integrations/mcp-server) for setup and configuration. + +### Sandboxed environments (Codex, Claude Code, etc.) + +Sandboxes that restrict process and network permissions can prevent bd from +controlling a Dolt server, causing persistent "database out of sync" errors +or `bd dolt stop` failing with "operation not permitted". + +bd auto-detects sandboxed environments and prints +`Sandbox detected, using direct mode`. If auto-detection fails, pass the +global `--sandbox` flag explicitly: + +```bash +bd --sandbox ready +bd --sandbox create "Fix bug" -p 1 +``` + +Sandbox mode disables Dolt auto-push so bd works without server control or +network access. Sync manually once outside the sandbox: + +```bash +bd dolt push +``` + +If staleness errors persist, `bd doctor --fix` forces a metadata refresh +(low risk β€” it updates tracking metadata, not issues). Background: +[GH#353](https://github.com/gastownhall/beads/issues/353). + +## Platform-Specific Issues + +### Windows: Path issues + +```pwsh +# Check if bd.exe is in PATH +where.exe bd + +# Add Go bin to PATH (permanently) +[Environment]::SetEnvironmentVariable( + "Path", + $env:Path + ";$env:USERPROFILE\go\bin", + [EnvironmentVariableTarget]::User +) + +# Reload PATH in current session +$env:Path = [Environment]::GetEnvironmentVariable("Path", "User") +``` + +### Windows: Firewall blocking the Dolt server + +In server mode, the Dolt server listens on loopback TCP. Allow `bd.exe` +through Windows Firewall: Windows Security β†’ Firewall & network protection β†’ +"Allow an app through firewall" β†’ add `bd.exe` for Private networks. + +### Windows: Controlled Folder Access blocks `bd init` + +**Symptom:** `bd init` hangs indefinitely with high CPU usage, and CTRL+C +doesn't work. Controlled Folder Access may block bd without showing a +notification, making this hard to diagnose without the `-v` flag: + +```pwsh +bd init -v +# Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified +``` + +**Solution:** Whitelist `bd.exe`: Windows Security β†’ Virus & threat +protection β†’ Ransomware protection β†’ Controlled folder access β†’ "Allow an +app through Controlled folder access" β†’ browse to `bd.exe` (typically +`%USERPROFILE%\go\bin\bd.exe`). Then retry `bd init`. + +### macOS: Gatekeeper blocking execution + +1. Verify the downloaded binary checksum matches the release `checksums.txt`. +2. If you used `scripts/install.sh`, note that macOS ad-hoc re-signing is + opt-in (`BEADS_INSTALL_RESIGN_MACOS=1`). +3. Approve the binary: + +```bash +# Remove quarantine attribute +xattr -d com.apple.quarantine /usr/local/bin/bd + +# Or: System Preferences β†’ Security & Privacy β†’ General β†’ "Allow anyway" +``` + +## Debug Environment Variables + +bd supports environment variables for debugging specific subsystems. Enable +them when troubleshooting or when requested by maintainers. + +| Variable | Purpose | Output | +|----------|---------|--------| +| `BD_DEBUG` | General debug logging | stderr | +| `BD_DEBUG_RPC` | RPC communication between CLI and Dolt server | stderr | +| `BD_DEBUG_SYNC` | Sync and import timestamp protection | stderr | +| `BD_DEBUG_ROUTING` | Issue routing and multi-repo resolution | stderr | +| `BD_DEBUG_FRESHNESS` | Database file replacement detection | server log | + +Set any of them to `1` to enable; `unset` to disable. + +```bash +# General debugging +BD_DEBUG=1 bd ready + +# Capture debug output to a file +BD_DEBUG=1 bd dolt push 2> debug.log + +# Sync timestamp protection, e.g.: +# [debug] Protected bd-123: local=2024-01-20T10:00:00Z >= incoming=2024-01-20T09:55:00Z +BD_DEBUG_SYNC=1 bd dolt push + +# Freshness output goes to the server log (server mode), not stderr +BD_DEBUG_FRESHNESS=1 bd dolt start +tail -f .beads/dolt-server.log | grep freshness +``` + +For multi-repo routing configuration, see [Routing](/multi-agent/routing). + ## Getting Help ### Debug output @@ -200,7 +763,8 @@ bd --verbose list ### Logs ```bash -cat .beads/dolt/sql-server.log +# Server mode (embedded mode runs in-process, no server log) +cat .beads/dolt-server.log ``` ### System info @@ -218,4 +782,5 @@ bd info --json uname -a ``` -Report at: https://github.com/gastownhall/beads/issues +Report at: https://github.com/gastownhall/beads/issues β€” or ask in +[GitHub Discussions](https://github.com/gastownhall/beads/discussions). diff --git a/docs/workflows/molecules.md b/docs/workflows/molecules.md index b3d138083..60d5c6df4 100644 --- a/docs/workflows/molecules.md +++ b/docs/workflows/molecules.md @@ -2,52 +2,116 @@ title: Molecules --- -Molecules are work graphs created from formulas. +Molecules are work graphs: epics whose children flow through `bd ready` as +dependency-ordered steps. They are usually instantiated from formulas, but a +formula is optional β€” any epic with children is a molecule. ## What is a Molecule? -A molecule is a persistent instance of a formula: +A molecule is a persistent instance of a proto (a cooked formula): - Contains steps with dependencies -- Tracked in `.beads/` (syncs with git) +- Persistent beads in the issue database, synced like any other bead - Steps map to issues with parent-child relationships +Under the hood, **a molecule is just an epic** β€” a parent bead with children β€” +plus workflow semantics: + +| Term | Meaning | When to use | +|------|---------|-------------| +| **Epic** | Parent issue with children | General term for hierarchical work | +| **Molecule** | Epic with execution intent | When discussing workflow traversal | +| **Proto** | Epic with the `template` label | Reusable pattern (optional) | + +Protos and formulas are optional layers for reusable patterns and complex +composition β€” most work needs only epics and dependencies. + ## Creating Molecules -### From Formula +### From a Formula ```bash -# Pour a formula into a molecule -bd pour [--var key=value] -``` - -**Example:** -```bash -bd pour release --var version=1.0.0 +# Cook the formula into a proto, then pour the proto into a molecule +bd cook release.formula.toml +bd mol pour release --var version=1.0.0 ``` This creates: - Parent issue: `bd-xyz` (the molecule root) - Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps) -### Listing Molecules +### Without a Formula + +Create the epic and wire the dependencies directly: ```bash -bd mol list -bd mol list --json +bd create "Feature X" -t epic +bd create "Design" -t task --parent +bd create "Implement" -t task --parent +bd create "Test" -t task --parent +bd dep add # implement needs design +bd dep add # test needs implement +``` + +If an ad-hoc epic turns out to be worth repeating, extract a reusable formula +from it with `bd mol distill `. + +### Finding Molecules + +```bash +bd mol current # Where you are in the molecule you're working +bd mol stale # Complete-but-still-open molecules +bd mol wisp list # Ephemeral molecules (wisps) ``` ### Viewing a Molecule ```bash -bd mol show -bd dep tree # Shows full hierarchy +bd mol show # Structure and variables +bd mol show --parallel # Highlight steps that can run concurrently +bd dep tree # Shows full hierarchy ``` ## Working with Molecules +### The Execution Model + +An agent picks up a molecule and executes ready children in parallel until +everything closes: + +``` +epic-root (assigned to agent) +β”œβ”€β”€ child.1 (no deps β†’ ready) ← execute in parallel +β”œβ”€β”€ child.2 (no deps β†’ ready) ← execute in parallel +β”œβ”€β”€ child.3 (needs child.1) β†’ blocked until child.1 closes +└── child.4 (needs child.2, child.3) β†’ blocked until both close +``` + +**Children are parallel by default.** Only explicit dependencies create +sequence. The multi-session loop: + +1. Get ready work: `bd ready --mol ` +2. Claim it: `bd update --claim` +3. Do the work +4. Close it: `bd close ` +5. Repeat until the molecule is done + +### Dependency Types + +Only some dependency types block execution: + +| Type | Semantics | Use case | +|------|-----------|----------| +| `blocks` | B can't start until A closes | Sequencing work | +| `parent-child` | If the parent is blocked, children are blocked | Hierarchy (children parallel by default) | +| `conditional-blocks` | B runs only if A fails | Error-handling paths | +| `waits-for` | B waits for all of A's dynamic children | Fan-in gates β€” see [Gates](/workflows/gates) | + +Non-blocking types (`related`, `discovered-from`, `replies-to`) link issues +without affecting execution. + ### Step Dependencies -Steps have `needs` dependencies: +In a formula, steps declare `needs`: ```toml [[steps]] @@ -56,10 +120,16 @@ title = "Implement feature" needs = ["design"] # Must complete design first ``` +On live issues, add the edge directly β€” the dependent comes first: + +```bash +bd dep add # B depends on A (B needs A) +``` + The `bd ready` command respects these: ```bash -bd ready # Only shows steps with completed dependencies +bd ready --mol # Only shows steps with completed dependencies ``` ### Progressing Through Steps @@ -72,7 +142,7 @@ bd update bd-xyz.1 --claim bd close bd-xyz.1 --reason "Done" # Check what's ready next -bd ready +bd ready --mol bd-xyz ``` ### Viewing Progress @@ -81,34 +151,88 @@ bd ready # See blocked steps bd blocked -# See molecule stats -bd stats +# Step-by-step status: [done] / [current] / [ready] / [blocked] / [pending] +bd mol current + +# Progress summary: completed/total, rate, ETA +bd mol progress ``` ## Molecule Lifecycle ``` -Formula (template) - ↓ bd pour +Formula (template source) + ↓ bd cook +Proto (template epic) + ↓ bd mol pour Molecule (instance) ↓ work steps Completed Molecule ↓ optional cleanup -Archived +Closed / Squashed / Burned +``` + +Closing the last child does not close the molecule root β€” epics stay open as +close-eligible work until closed explicitly (`bd epic close-eligible` sweeps +them). For cleanup of the beads themselves: + +- `bd mol squash ` condenses a molecule's ephemeral children into a + permanent digest issue. +- `bd mol burn ` deletes a molecule outright, no digest β€” for abandoned + or test runs. + +See [Wisps](/workflows/wisps) for the ephemeral lifecycle these commands +usually serve. + +## Bonding: Connecting Work Graphs + +**Bond** means creating a dependency between two work graphs. When molecule A +blocks molecule B, completing A unblocks B and an agent can continue from A +into B β€” one compound workflow that can span days. + +```bash +bd mol bond A B # B depends on A (sequential by default) +bd mol bond A B --type parallel # B runs alongside A +bd mol bond A B --type conditional # B runs only if A fails +``` + +The command is polymorphic over its operands: + +| Operands | What happens | +|----------|--------------| +| proto + proto | Compound proto (reusable template) | +| proto + molecule | Spawns the proto as new issues, attached to the molecule | +| molecule + molecule | Joins them into a compound molecule | +| formula + anything | The formula is cooked inline first | + +Spawned issues follow the target's phase (persistent or ephemeral) by +default. Override with `--pour` (force persistent) or `--ephemeral` (force +ephemeral) β€” see [Wisps](/workflows/wisps). + +### Dynamic Bonding + +When the number of children isn't known until runtime, bond in a loop with +`--ref` to get readable child IDs instead of random hashes: + +```bash +# One arm per discovered worker +bd mol bond mol-worker-arm bd-patrol --ref arm-{{name}} --var name=ace +# Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture) ``` ## Advanced Features ### Bond Points -Formulas can define bond points for composition: +Formulas can define bond points β€” named attachment sites for composition. +Each names a step to attach `before_step` or `after_step` (with optional +`parallel = true`): ```toml -[compose] [[compose.bond_points]] id = "entry" -step = "design" -position = "before" +description = "Attach setup work here" +before_step = "design" ``` ### Hooks @@ -118,23 +242,33 @@ actions. The historical `on_complete.run` example was invalid: `run` is not a formula field, and `on_complete` runtime expansion is tracked separately until it is wired end to end. -### Pinning Work +### Assigning Molecules -Assign molecules to agents: +Assign the molecule root to an agent at pour time, then track where each +agent is: ```bash -# Pin to current agent -bd pin bd-xyz --start - -# Check what's pinned -bd hook +bd mol pour mol-feature --assignee # Assign on creation +bd mol current --for # Where that agent is ``` +## Agent Pitfalls + +1. **Temporal language inverts dependencies.** "Phase 1 comes before Phase 2" + tempts `bd dep add phase1 phase2` β€” backwards. Use requirement language: + "Phase 2 needs Phase 1" is `bd dep add phase2 phase1`. Verify with + `bd blocked`. +2. **Numbered steps don't create sequence.** Steps named "Step 1/2/3" still + run in parallel until you add dependencies between them. +3. **Forgetting to close work.** Blocked issues stay blocked forever if their + blockers aren't closed: `bd close --reason "Done"`. + ## Example Workflow ```bash # 1. Create molecule from formula -bd pour feature-workflow --var name="dark-mode" +bd cook feature-workflow.formula.toml +bd mol pour feature-workflow --var name="dark-mode" # 2. View structure bd dep tree bd-xyz @@ -144,7 +278,7 @@ bd update bd-xyz.1 --claim # 4. Complete and progress bd close bd-xyz.1 -bd ready # Shows next steps +bd ready --mol bd-xyz # Shows next steps # 5. Continue until complete ``` diff --git a/engdocs/DOC_INVENTORY.md b/engdocs/DOC_INVENTORY.md index 02ae3e99e..633be7bc2 100644 --- a/engdocs/DOC_INVENTORY.md +++ b/engdocs/DOC_INVENTORY.md @@ -1,6 +1,6 @@ # Documentation Disposition Inventory -Reviewed: 2026-07-07 +Reviewed: 2026-07-07 (paths updated 2026-07-10 for the Mintlify port: user docs now live in the docs/ site tree; this ledger and other internal docs live in engdocs/) CI cleanup entry added: 2026-05-28 @@ -28,11 +28,11 @@ freshness source. |---|---| | `CLI_REFERENCE.md` | Generated from `bd help --all`. | | `plugins/beads/skills/beads/resources/CLI_REFERENCE.md` | Pointer-only doc: must link to live CLI help and canonical generated `docs/CLI_REFERENCE.md`; do not duplicate generated command tables. | -| `CONFIG.md` | `Last reviewed:` marker tied to `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. | -| `SETUP.md` | `Last reviewed:` marker tied to `cmd/bd/setup*.go` and `internal/recipes/`. | -| `ADO_CONFIG.md` | `Last reviewed:` marker tied to `cmd/bd/ado*.go` and `internal/ado/`. | -| `JSON_SCHEMA.md` | `Last reviewed:` marker tied to `cmd/bd/output.go`, `cmd/bd/errors.go`, and protocol tests. | -| `RECOVERY.md` | `Last reviewed:` marker tied to `cmd/bd/init*.go` safety code and tests. | +| `reference/configuration.md` | `Last reviewed:` marker tied to `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. (Mintlify port: absorbed `CONFIG.md`.) | +| `getting-started/ide-setup.md` | `Last reviewed:` marker tied to `cmd/bd/setup*.go` and `internal/recipes/`. (Mintlify port: absorbed `SETUP.md`.) | +| `integrations/azure-devops.md` | `Last reviewed:` marker tied to `cmd/bd/ado*.go` and `internal/ado/`. (Mintlify port: was `ADO_CONFIG.md`.) | +| `reference/json-schema.md` | `Last reviewed:` marker tied to `cmd/bd/output.go`, `cmd/bd/errors.go`, and protocol tests. (Mintlify port: was `JSON_SCHEMA.md`.) | +| `recovery/init-safety.md` | `Last reviewed:` marker tied to `cmd/bd/init*.go` safety code and tests. (Mintlify port: was `RECOVERY.md`.) | | `ERROR_HANDLING.md` | `Last reviewed:` marker tied to current command error exits and JSON error helpers. | | `LINTING.md` | `Last reviewed:` marker tied to `.golangci.yml` and current lint output. | | `CI_CLEANUP_PLAN.md` | `Last reviewed:` marker tied to CI audit, workflow files, package manifests, and maintainer decision review. | diff --git a/scripts/check-doc-freshness.sh b/scripts/check-doc-freshness.sh index 754b1285a..7b07cdc2f 100755 --- a/scripts/check-doc-freshness.sh +++ b/scripts/check-doc-freshness.sh @@ -17,11 +17,11 @@ TODAY="${DOC_FRESHNESS_TODAY:-$(date +%F)}" ERRORS=0 DOCS=( - "docs/CONFIG.md|cmd/bd/main.go;cmd/bd/config.go;internal/configfile/" - "docs/SETUP.md|cmd/bd/setup*.go;internal/recipes/" - "docs/ADO_CONFIG.md|cmd/bd/ado*.go;internal/ado/" - "docs/JSON_SCHEMA.md|cmd/bd/output.go;cmd/bd/errors.go;cmd/bd/protocol/json_contract_test.go" - "docs/RECOVERY.md|cmd/bd/init.go;cmd/bd/init_safety.go;cmd/bd/init_safety_test.go" + "docs/reference/configuration.md|cmd/bd/main.go;cmd/bd/config.go;internal/configfile/" + "docs/getting-started/ide-setup.md|cmd/bd/setup*.go;internal/recipes/" + "docs/integrations/azure-devops.md|cmd/bd/ado*.go;internal/ado/" + "docs/reference/json-schema.md|cmd/bd/output.go;cmd/bd/errors.go;cmd/bd/protocol/json_contract_test.go" + "docs/recovery/init-safety.md|cmd/bd/init.go;cmd/bd/init_safety.go;cmd/bd/init_safety_test.go" "engdocs/ERROR_HANDLING.md|cmd/bd/*.go;cmd/bd/errors.go" "engdocs/LINTING.md|.golangci.yml" "engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/" diff --git a/test/docsync/docsync_test.go b/test/docsync/docsync_test.go index b2f2faa0b..398ec5bd0 100644 --- a/test/docsync/docsync_test.go +++ b/test/docsync/docsync_test.go @@ -43,6 +43,9 @@ var docsPublishExemptions = map[string]bool{ "RECOVERY.md": true, // pointer stub; bd dolt output references its runbook anchors "JSON_SCHEMA.md": true, // pointer stub; bd schema-migration output references it "SYNC_CONCEPTS.md": true, // pointer stub; bd init agent templates link it on GitHub + "SETUP.md": true, // pointer stub; bd prime help prints docs/SETUP.md#policy-profiles + "INSTALLING.md": true, // pointer stub; bd storage-backend help references it + "GIT_INTEGRATION.md": true, // pointer stub; bd jj-alias output links its jujutsu section } // rootDocFiles are the curated root-level markdown files whose local links