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

feat: add llms.txt standard support for AI agent discoverability (#784)

Browse Source 
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml
from joyshmitz's PR. Fixed workflow to trigger on main branch instead of
docs/docusaurus-site.

Features:
- Docusaurus documentation site with llms.txt support
- Environment-variable driven config (defaults to steveyegge org)
- Automated llms-full.txt generation from docs
- GitHub Pages deployment workflow

Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com>

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

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

Executed-By: beads/crew/dave
Rig: beads
Role: crew
This commit is contained in:
Steve Yegge
2025-12-30 18:27:36 -08:00
parent 2e55f2838a
commit 584608a14e
54 changed files with 32920 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
website/docs/architecture/index.md Normal file
View File

@@ -0,0 +1,287 @@
---
sidebar_position: 1
title: Architecture Overview
description: Understanding Beads' three-layer data model
---
# Architecture Overview
This document explains how Beads' three-layer architecture works: Git, JSONL, and SQLite.
## The Three Layers
Beads uses a layered architecture where each layer serves a specific purpose:
```mermaid
flowchart TD
subgraph GIT["🗂️ Layer 1: Git Repository"]
G[(".beads/*.jsonl<br/><i>Historical Source of Truth</i>")]
end
subgraph JSONL["📄 Layer 2: JSONL Files"]
J[("issues.jsonl<br/><i>Operational Source of Truth</i>")]
end
subgraph SQL["⚡ Layer 3: SQLite"]
D[("beads.db<br/><i>Fast Queries / Derived State</i>")]
end
G <-->|"bd sync"| J
J -->|"rebuild"| D
D -->|"append"| J
U((👤 User)) -->|"bd create<br/>bd update"| D
D -->|"bd list<br/>bd show"| U
style GIT fill:#2d5a27,stroke:#4a9c3e,color:#fff
style JSONL fill:#1a4a6e,stroke:#3a8ac4,color:#fff
style SQL fill:#6b3a6b,stroke:#a45ea4,color:#fff
```
:::info Historical vs Operational Truth
**Git** is the *historical* source of truth—commits preserve the full history of your issues and can be recovered from any point in time.
**JSONL** is the *operational* source of truth—when recovering from database corruption, Beads rebuilds SQLite from JSONL files, not directly from Git commits.
This layered model enables recovery: if SQLite is corrupted but JSONL is intact, run `bd sync --import-only` to rebuild. If JSONL is corrupted, recover it from Git history first.
:::
### Layer 1: Git Repository
Git is the *historical* source of truth. All issue data lives in the repository alongside your code, with full history preserved in commits.
**Why Git?**
- Issues travel with the code
- No external service dependency
- Full history via Git log (recover any point in time)
- Works offline
- Enables multi-machine and multi-agent workflows
### Layer 2: JSONL Files
JSONL (JSON Lines) files store issue data in an append-only format. This is the *operational* source of truth—SQLite databases are rebuilt from JSONL.
**Location:** `.beads/*.jsonl`
**Why JSONL?**
- Human-readable and inspectable
- Git-mergeable (append-only reduces conflicts)
- Portable across systems
- Can be recovered from Git history
- **Recovery source**: `bd sync --import-only` rebuilds SQLite from JSONL
### Layer 3: SQLite Database
SQLite provides fast local queries without network latency. This is *derived state*—it can always be rebuilt from JSONL.
**Location:** `.beads/beads.db`
**Why SQLite?**
- Instant queries (no network)
- Complex filtering and sorting
- Derived from JSONL (always rebuildable)
- Safe to delete and rebuild: `rm .beads/beads.db* && bd sync --import-only`
## Data Flow
### Write Path
```text
User runs bd create
→ SQLite updated
→ JSONL appended
→ Git commit (on sync)
```
### Read Path
```text
User runs bd list
→ SQLite queried
→ Results returned immediately
```
### Sync Path
```text
User runs bd sync
→ Git pull
→ JSONL merged
→ SQLite rebuilt if needed
→ Git push
```
### Sync Modes
Beads provides specialized sync modes for different recovery scenarios:
#### Standard Sync
```bash
bd sync
```
Normal bidirectional sync: pulls remote changes, merges JSONL, rebuilds SQLite if needed, pushes local changes.
#### Import-Only Mode
```bash
bd sync --import-only
```
Rebuilds the SQLite database from JSONL without pushing changes. Use this when:
- SQLite is corrupted or missing
- Recovering from a fresh clone
- Rebuilding after database migration issues
This is the safest recovery option when JSONL is intact.
#### Force Rebuild Mode
```bash
bd sync --force-rebuild
```
Forces complete SQLite rebuild from JSONL, discarding any SQLite-only state. Use with caution:
- More aggressive than `--import-only`
- May lose any uncommitted database state
- Recommended when standard sync fails repeatedly
### Multi-Machine Sync Considerations
When working across multiple machines or clones:
1. **Always sync before switching machines**
```bash
bd sync # Push changes before leaving
```
2. **Pull before creating new issues**
```bash
bd sync # Pull changes first on new machine
bd create "New issue"
```
3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, conflicts may occur
See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3).
## The Daemon
The Beads daemon (`bd daemon`) handles background synchronization:
- Watches for file changes
- Triggers sync on changes
- Keeps SQLite in sync with JSONL
- Manages lock files
:::tip
The daemon is optional but recommended for multi-agent workflows.
:::
### Running Without the Daemon
For CI/CD pipelines, containers, and single-use scenarios, run commands without spawning a daemon:
```bash
bd --no-daemon create "CI-generated issue"
bd --no-daemon sync
```
**When to use `--no-daemon`:**
- CI/CD pipelines (Jenkins, GitHub Actions)
- Docker containers
- Ephemeral environments
- Scripts that should not leave background processes
- Debugging daemon-related issues
### Daemon in Multi-Clone Scenarios
:::warning Race Conditions in Multi-Clone Workflows
When multiple git clones of the same repository run daemons simultaneously, race conditions can occur during push/pull operations. This is particularly common in:
- Multi-agent AI workflows (multiple Claude/GPT instances)
- Developer workstations with multiple checkouts
- Worktree-based development workflows
**Prevention:**
1. Use `bd daemons killall` before switching between clones
2. Ensure only one clone's daemon is active at a time
3. Consider `--no-daemon` mode for automated workflows
:::
See [Sync Failures Recovery](/recovery/sync-failures) for daemon race condition troubleshooting (Pattern B2).
## Recovery Model
The three-layer architecture makes recovery straightforward because each layer can rebuild from the one above it:
1. **Lost SQLite?** → Rebuild from JSONL: `bd sync --import-only`
2. **Lost JSONL?** → Recover from Git history: `git checkout HEAD~1 -- .beads/issues.jsonl`
3. **Conflicts?** → Git merge, then rebuild
### Universal Recovery Sequence
The following sequence demonstrates how the architecture enables quick recovery. For detailed procedures, see [Recovery Runbooks](/recovery).
This sequence resolves the majority of reported issues:
```bash
bd daemons killall # Stop daemons (prevents race conditions)
git worktree prune # Clean orphaned worktrees
rm .beads/beads.db* # Remove potentially corrupted database
bd sync --import-only # Rebuild from JSONL source of truth
```
:::danger Never Use `bd doctor --fix`
Analysis of 54 GitHub issues revealed that `bd doctor --fix` frequently causes **more damage** than the original problem:
- Deletes "circular" dependencies that are actually valid parent-child relationships
- False positive detection removes legitimate issue links
- Recovery after `--fix` is harder than recovery from the original issue
**Safe alternatives:**
- `bd doctor` — Diagnostic only, no changes made
- `bd blocked` — Check which issues are blocked and why
- `bd show <issue-id>` — Inspect a specific issue's state
If `bd doctor` reports problems, investigate each one manually before taking any action.
:::
See [Recovery](/recovery) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for `bd doctor --fix` recovery (Pattern D4).
## Design Decisions
### Why not just SQLite?
SQLite alone doesn't travel with Git or merge well across branches. Binary database files create merge conflicts that are nearly impossible to resolve.
### Why not just JSONL?
JSONL is slow for complex queries. Scanning thousands of lines for filtering and sorting is inefficient. SQLite provides indexed lookups in milliseconds.
### Why append-only JSONL?
Append-only format minimizes Git merge conflicts. When two branches add issues, Git can cleanly merge by concatenating the additions. Edit operations append new records rather than modifying existing lines.
### Why not a server?
Beads is designed for offline-first, local-first development. No server means no downtime, no latency, no vendor lock-in, and full functionality on airplanes or in restricted networks.
### Trade-offs
| Benefit | Trade-off |
|---------|-----------|
| Works offline | No real-time collaboration |
| Git-native history | Requires Git knowledge |
| No server dependency | No web UI or mobile app |
| Local-first speed | Manual sync required |
| Append-only merging | JSONL files grow over time |
### When NOT to use Beads
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
- [Recovery Runbooks](/recovery) — Step-by-step procedures for common issues
- [CLI Reference](/cli-reference) — Complete command documentation
- [Getting Started](/) — Installation and first steps

240
website/docs/cli-reference/dependencies.md Normal file
View File

@@ -0,0 +1,240 @@
---
id: dependencies
title: Dependency Commands
sidebar_position: 4
---
# Dependency Commands
Commands for managing issue dependencies.
## bd dep add
Add a dependency between issues.
```bash
bd dep add <dependent> <dependency> [flags]
```
**Semantics:** `<dependent>` depends on `<dependency>` (dependency blocks dependent).
**Flags:**
```bash
--type Dependency type (blocks|related|discovered-from)
--json JSON output
```
**Examples:**
```bash
# bd-2 depends on bd-1 (bd-1 blocks bd-2)
bd dep add bd-2 bd-1
# Soft relationship
bd dep add bd-2 bd-1 --type related
# JSON output
bd dep add bd-2 bd-1 --json
```
## bd dep remove
Remove a dependency.
```bash
bd dep remove <dependent> <dependency> [flags]
```
**Examples:**
```bash
bd dep remove bd-2 bd-1
bd dep remove bd-2 bd-1 --json
```
## bd dep tree
Display dependency tree.
```bash
bd dep tree <id> [flags]
```
**Flags:**
```bash
--depth Maximum depth to display
--json JSON output
```
**Examples:**
```bash
bd dep tree bd-42
bd dep tree bd-42 --depth 3
bd dep tree bd-42 --json
```
**Output:**
```
Dependency tree for bd-42:
> bd-42: Add authentication [P2] (open)
> bd-41: Create API [P2] (open)
> bd-40: Set up database [P1] (closed)
```
## bd dep cycles
Detect circular dependencies.
```bash
bd dep cycles [flags]
```
**Flags:**
```bash
--json JSON output
```
**Examples:**
```bash
bd dep cycles
bd dep cycles --json
```
## bd ready
Show issues with no blockers.
```bash
bd ready [flags]
```
**Flags:**
```bash
--priority Filter by priority
--type Filter by type
--label Filter by label
--json JSON output
```
**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --type bug
bd ready --json
```
**Output:**
```
Ready work (3 issues with no blockers):
1. [P1] bd-40: Set up database
2. [P2] bd-45: Write tests
3. [P3] bd-46: Update docs
```
## bd blocked
Show blocked issues and their blockers.
```bash
bd blocked [flags]
```
**Flags:**
```bash
--json JSON output
```
**Examples:**
```bash
bd blocked
bd blocked --json
```
**Output:**
```
Blocked issues (2 issues):
bd-42: Add authentication
Blocked by: bd-41 (open)
bd-41: Create API
Blocked by: bd-40 (in_progress)
```
## bd relate
Create a soft relationship between issues.
```bash
bd relate <id1> <id2> [flags]
```
**Examples:**
```bash
bd relate bd-42 bd-43
bd relate bd-42 bd-43 --json
```
## bd duplicate
Mark an issue as duplicate.
```bash
bd duplicate <id> --of <canonical> [flags]
```
**Examples:**
```bash
bd duplicate bd-43 --of bd-42
bd duplicate bd-43 --of bd-42 --json
```
## bd supersede
Mark an issue as superseding another.
```bash
bd supersede <old> --with <new> [flags]
```
**Examples:**
```bash
bd supersede bd-42 --with bd-50
bd supersede bd-42 --with bd-50 --json
```
## Understanding Dependencies
### Blocking vs Non-blocking
| Type | Blocks Ready Queue | Use Case |
|------|-------------------|----------|
| `blocks` | Yes | Hard dependency |
| `parent-child` | No | Epic/subtask hierarchy |
| `discovered-from` | No | Track origin |
| `related` | No | Soft link |
| `duplicates` | No | Mark duplicate |
| `supersedes` | No | Version chain |
### Dependency Direction
```bash
# bd-2 depends on bd-1
# Meaning: bd-1 must complete before bd-2 can start
bd dep add bd-2 bd-1
# After bd-1 closes:
bd close bd-1
bd ready # bd-2 now appears
```
### Avoiding Cycles
```bash
# Check before adding complex dependencies
bd dep cycles
# If cycle detected, remove one dependency
bd dep remove bd-A bd-B
```

215
website/docs/cli-reference/essential.md Normal file
View File

@@ -0,0 +1,215 @@
---
id: essential
title: Essential Commands
sidebar_position: 2
---
# Essential Commands
The most important commands for daily use.
## bd create
Create a new issue.
```bash
bd create <title> [flags]
```
**Flags:**
| Flag | Short | Description |
|------|-------|-------------|
| `--type` | `-t` | Issue type: bug, feature, task, epic, chore |
| `--priority` | `-p` | Priority: 0-4 (0=critical, 4=backlog) |
| `--description` | `-d` | Detailed description |
| `--labels` | `-l` | Comma-separated labels |
| `--parent` | | Parent issue ID (for hierarchical) |
| `--deps` | | Dependencies (e.g., `discovered-from:bd-42`) |
| `--json` | | JSON output |
**Examples:**
```bash
bd create "Fix login bug" -t bug -p 1
bd create "Add dark mode" -t feature -p 2 --description="User requested"
bd create "Subtask" --parent bd-42 -p 2
bd create "Found during work" --deps discovered-from:bd-42 --json
```
## bd list
List issues with filters.
```bash
bd list [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | Filter by status: open, in_progress, closed |
| `--priority` | Filter by priority (comma-separated) |
| `--type` | Filter by type (comma-separated) |
| `--label-any` | Issues with any of these labels |
| `--label-all` | Issues with all of these labels |
| `--json` | JSON output |
**Examples:**
```bash
bd list --status open
bd list --priority 0,1 --type bug
bd list --label-any urgent,critical --json
```
## bd show
Show issue details.
```bash
bd show <id> [flags]
```
**Examples:**
```bash
bd show bd-42
bd show bd-42 --json
bd show bd-42 bd-43 bd-44 # Multiple issues
```
## bd update
Update issue fields.
```bash
bd update <id> [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | New status |
| `--priority` | New priority |
| `--title` | New title |
| `--description` | New description |
| `--add-label` | Add label |
| `--remove-label` | Remove label |
| `--json` | JSON output |
**Examples:**
```bash
bd update bd-42 --status in_progress
bd update bd-42 --priority 0 --add-label urgent
bd update bd-42 --title "Updated title" --json
```
## bd close
Close an issue.
```bash
bd close <id> [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--reason` | Closure reason |
| `--json` | JSON output |
**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in PR #123"
bd close bd-42 --json
```
## bd ready
Show issues ready to work on (no blockers).
```bash
bd ready [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--priority` | Filter by priority |
| `--type` | Filter by type |
| `--json` | JSON output |
**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --json
```
## bd blocked
Show blocked issues and their blockers.
```bash
bd blocked [flags]
```
**Examples:**
```bash
bd blocked
bd blocked --json
```
## bd sync
Force immediate sync to git.
```bash
bd sync [flags]
```
Performs:
1. Export database to JSONL
2. Git add `.beads/issues.jsonl`
3. Git commit
4. Git push
**Examples:**
```bash
bd sync
bd sync --json
```
## bd info
Show system information.
```bash
bd info [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--whats-new` | Show recent version changes |
| `--schema` | Show database schema |
| `--json` | JSON output |
**Examples:**
```bash
bd info
bd info --whats-new
bd info --json
```
## bd stats
Show project statistics.
```bash
bd stats [flags]
```
**Examples:**
```bash
bd stats
bd stats --json
```

185
website/docs/cli-reference/index.md Normal file
View File

@@ -0,0 +1,185 @@
---
id: index
title: CLI Reference
sidebar_position: 1
---
# CLI Reference
Complete reference for all `bd` commands.
## Command Structure
```bash
bd [global-flags] <command> [command-flags] [arguments]
```
### Global Flags
| Flag | Description |
|------|-------------|
| `--db <path>` | Use specific database file |
| `--no-daemon` | Bypass daemon, direct database access |
| `--json` | Output in JSON format |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Verbose output |
| `--version` | Show version |
| `--help` | Show help |
## Command Categories
### Essential Commands
Most frequently used:
| Command | Description |
|---------|-------------|
| `bd create` | Create new issue |
| `bd list` | List issues with filters |
| `bd show` | Show issue details |
| `bd update` | Update issue fields |
| `bd close` | Close an issue |
| `bd ready` | Show unblocked work |
| `bd sync` | Force sync to git |
### Issue Management
| Command | Description |
|---------|-------------|
| `bd create` | Create issue |
| `bd show` | Show details |
| `bd update` | Update fields |
| `bd close` | Close issue |
| `bd delete` | Delete issue |
| `bd reopen` | Reopen closed issue |
### Dependencies
| Command | Description |
|---------|-------------|
| `bd dep add` | Add dependency |
| `bd dep remove` | Remove dependency |
| `bd dep tree` | Show dependency tree |
| `bd dep cycles` | Detect circular dependencies |
| `bd blocked` | Show blocked issues |
| `bd ready` | Show unblocked issues |
### Labels & Comments
| Command | Description |
|---------|-------------|
| `bd label add` | Add label to issue |
| `bd label remove` | Remove label |
| `bd label list` | List all labels |
| `bd comment add` | Add comment |
| `bd comment list` | List comments |
### Sync & Export
| Command | Description |
|---------|-------------|
| `bd sync` | Full sync cycle |
| `bd export` | Export to JSONL |
| `bd import` | Import from JSONL |
| `bd migrate` | Migrate database schema |
### System
| Command | Description |
|---------|-------------|
| `bd init` | Initialize beads in project |
| `bd info` | Show system info |
| `bd version` | Show version |
| `bd config` | Manage configuration |
| `bd daemons` | Manage daemons |
| `bd hooks` | Manage git hooks |
### Workflows
| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol` | Manage molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |
## Quick Reference
### Creating Issues
```bash
# Basic
bd create "Title" -t task -p 2
# With description
bd create "Title" --description="Details here" -t bug -p 1
# With labels
bd create "Title" -l "backend,urgent"
# As child of epic
bd create "Subtask" --parent bd-42
# With discovered-from link
bd create "Found bug" --deps discovered-from:bd-42
# JSON output
bd create "Title" --json
```
### Querying Issues
```bash
# All open issues
bd list --status open
# High priority bugs
bd list --status open --priority 0,1 --type bug
# With specific labels
bd list --label-any urgent,critical
# JSON output
bd list --json
```
### Working with Dependencies
```bash
# Add: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View tree
bd dep tree bd-2
# Find cycles
bd dep cycles
# What's ready to work?
bd ready
# What's blocked?
bd blocked
```
### Syncing
```bash
# Full sync (export + commit + push)
bd sync
# Force export
bd export
# Import from file
bd import -i .beads/issues.jsonl
```
## See Also
- [Essential Commands](/cli-reference/essential)
- [Issue Commands](/cli-reference/issues)
- [Dependency Commands](/cli-reference/dependencies)
- [Label Commands](/cli-reference/labels)
- [Sync Commands](/cli-reference/sync)

230
website/docs/cli-reference/issues.md Normal file
View File

@@ -0,0 +1,230 @@
---
id: issues
title: Issue Commands
sidebar_position: 3
---
# Issue Commands
Commands for managing issues.
## bd create
Create a new issue.
```bash
bd create <title> [flags]
```
**All flags:**
```bash
--type, -t Issue type (bug|feature|task|epic|chore)
--priority, -p Priority 0-4
--description, -d Detailed description
--labels, -l Comma-separated labels
--parent Parent issue ID
--deps Dependencies (type:id format)
--assignee Assigned user
--json JSON output
```
**Examples:**
```bash
# Bug with high priority
bd create "Login fails with special chars" -t bug -p 1
# Feature with description
bd create "Add export to PDF" -t feature -p 2 \
--description="Users want to export reports as PDF files"
# Task with labels
bd create "Update CI config" -t task -l "ci,infrastructure"
# Epic with children
bd create "Auth System" -t epic -p 1
bd create "Design login UI" --parent bd-42
bd create "Implement backend" --parent bd-42
# Discovered issue
bd create "Found SQL injection" -t bug -p 0 \
--deps discovered-from:bd-42 --json
```
## bd show
Display issue details.
```bash
bd show <id>... [flags]
```
**Flags:**
```bash
--full Show all fields including comments
--json JSON output
```
**Examples:**
```bash
bd show bd-42
bd show bd-42 --full
bd show bd-42 bd-43 bd-44 --json
```
## bd update
Update issue fields.
```bash
bd update <id> [flags]
```
**All flags:**
```bash
--status New status (open|in_progress|closed)
--priority New priority (0-4)
--title New title
--description New description
--type New type
--add-label Add label(s)
--remove-label Remove label(s)
--assignee New assignee
--json JSON output
```
**Examples:**
```bash
# Start work
bd update bd-42 --status in_progress
# Escalate priority
bd update bd-42 --priority 0 --add-label urgent
# Change title and description
bd update bd-42 --title "New title" --description="Updated description"
# Multiple changes
bd update bd-42 --status in_progress --priority 1 --add-label "in-review" --json
```
## bd close
Close an issue.
```bash
bd close <id> [flags]
```
**Flags:**
```bash
--reason Closure reason (stored in comment)
--json JSON output
```
**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in commit abc123"
bd close bd-42 --reason "Duplicate of bd-43" --json
```
## bd reopen
Reopen a closed issue.
```bash
bd reopen <id> [flags]
```
**Examples:**
```bash
bd reopen bd-42
bd reopen bd-42 --json
```
## bd delete
Delete an issue.
```bash
bd delete <id> [flags]
```
**Flags:**
```bash
--force, -f Skip confirmation
--json JSON output
```
**Examples:**
```bash
bd delete bd-42
bd delete bd-42 -f --json
```
**Note:** Deletions are tracked in `.beads/deletions.jsonl` for sync.
## bd search
Search issues by text.
```bash
bd search <query> [flags]
```
**Flags:**
```bash
--status Filter by status
--type Filter by type
--json JSON output
```
**Examples:**
```bash
bd search "authentication"
bd search "login bug" --status open
bd search "API" --type feature --json
```
## bd duplicates
Find and manage duplicate issues.
```bash
bd duplicates [flags]
```
**Flags:**
```bash
--auto-merge Automatically merge all duplicates
--dry-run Preview without changes
--json JSON output
```
**Examples:**
```bash
bd duplicates
bd duplicates --auto-merge
bd duplicates --dry-run --json
```
## bd merge
Merge duplicate issues.
```bash
bd merge <source>... --into <target> [flags]
```
**Flags:**
```bash
--into Target issue to merge into
--dry-run Preview without changes
--json JSON output
```
**Examples:**
```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run --json
```

125
website/docs/cli-reference/labels.md Normal file
View File

@@ -0,0 +1,125 @@
---
id: labels
title: Labels & Comments
sidebar_position: 5
---
# Labels & Comments
Commands for managing labels and comments.
## Labels
### Adding Labels
```bash
# During creation
bd create "Task" -l "backend,urgent"
# To existing issue
bd update bd-42 --add-label urgent
bd update bd-42 --add-label "backend,security"
```
### Removing Labels
```bash
bd update bd-42 --remove-label urgent
```
### Listing Labels
```bash
# All labels in use
bd label list
bd label list --json
# Issues with specific labels
bd list --label-any urgent,critical
bd list --label-all backend,security
```
### Label Conventions
Suggested label categories:
| Category | Examples | Purpose |
|----------|----------|---------|
| Type | `bug`, `feature`, `docs` | Issue classification |
| Priority | `urgent`, `critical` | Urgency markers |
| Area | `backend`, `frontend`, `api` | Code area |
| Status | `blocked`, `needs-review` | Workflow state |
| Size | `small`, `medium`, `large` | Effort estimate |
## Comments
### Adding Comments
```bash
bd comment add bd-42 "Working on this now"
bd comment add bd-42 --message "Found the bug in auth.go:45"
```
### Listing Comments
```bash
bd comment list bd-42
bd comment list bd-42 --json
```
### Viewing with Issue
```bash
bd show bd-42 --full # Includes comments
```
## Filtering by Labels
### Any Match (OR)
```bash
# Issues with urgent OR critical
bd list --label-any urgent,critical
```
### All Match (AND)
```bash
# Issues with BOTH backend AND security
bd list --label-all backend,security
```
### Combined Filters
```bash
# Open bugs with urgent label
bd list --status open --type bug --label-any urgent --json
```
## Bulk Operations
### Add Label to Multiple Issues
```bash
# Using shell
for id in bd-42 bd-43 bd-44; do
bd update $id --add-label "sprint-1"
done
```
### Find and Label
```bash
# Label all open bugs as needs-triage
bd list --status open --type bug --json | \
jq -r '.[].id' | \
xargs -I {} bd update {} --add-label needs-triage
```
## Best Practices
1. **Keep labels lowercase** - `backend` not `Backend`
2. **Use hyphens for multi-word** - `needs-review` not `needs_review`
3. **Be consistent** - Establish team conventions
4. **Don't over-label** - 2-4 labels per issue is typical
5. **Review periodically** - Remove unused labels

208
website/docs/cli-reference/sync.md Normal file
View File

@@ -0,0 +1,208 @@
---
id: sync
title: Sync & Export
sidebar_position: 6
---
# Sync & Export Commands
Commands for synchronizing with git.
## bd sync
Full sync cycle: export, commit, push.
```bash
bd sync [flags]
```
**What it does:**
1. Exports database to `.beads/issues.jsonl`
2. Stages the JSONL file
3. Commits with auto-generated message
4. Pushes to remote
**Flags:**
```bash
--json JSON output
--dry-run Preview without changes
```
**Examples:**
```bash
bd sync
bd sync --json
```
**When to use:**
- End of work session
- Before switching branches
- After significant changes
## bd export
Export database to JSONL.
```bash
bd export [flags]
```
**Flags:**
```bash
--output, -o Output file (default: .beads/issues.jsonl)
--dry-run Preview without writing
--json JSON output
```
**Examples:**
```bash
bd export
bd export -o backup.jsonl
bd export --dry-run
```
## bd import
Import from JSONL file.
```bash
bd import -i <file> [flags]
```
**Flags:**
```bash
--input, -i Input file (required)
--dry-run Preview without changes
--orphan-handling How to handle missing parents
--dedupe-after Run duplicate detection after import
--json JSON output
```
**Orphan handling modes:**
| Mode | Behavior |
|------|----------|
| `allow` | Import orphans without validation (default) |
| `resurrect` | Restore deleted parents as tombstones |
| `skip` | Skip orphaned children with warning |
| `strict` | Fail if parent missing |
**Examples:**
```bash
bd import -i .beads/issues.jsonl
bd import -i backup.jsonl --dry-run
bd import -i issues.jsonl --orphan-handling resurrect
bd import -i issues.jsonl --dedupe-after --json
```
## bd migrate
Migrate database schema.
```bash
bd migrate [flags]
```
**Flags:**
```bash
--inspect Show migration plan (for agents)
--dry-run Preview without changes
--cleanup Remove old files after migration
--yes Skip confirmation
--json JSON output
```
**Examples:**
```bash
bd migrate --inspect --json
bd migrate --dry-run
bd migrate
bd migrate --cleanup --yes
```
## bd hooks
Manage git hooks.
```bash
bd hooks <subcommand> [flags]
```
**Subcommands:**
| Command | Description |
|---------|-------------|
| `install` | Install git hooks |
| `uninstall` | Remove git hooks |
| `status` | Check hook status |
**Examples:**
```bash
bd hooks install
bd hooks status
bd hooks uninstall
```
## Auto-Sync Behavior
### With Daemon (Default)
The daemon handles sync automatically:
- Exports to JSONL after changes (5s debounce)
- Imports from JSONL when newer
### Without Daemon
Use `--no-daemon` flag:
- Changes only written to SQLite
- Must manually export/sync
```bash
bd --no-daemon create "Task"
bd export # Manual export needed
```
## Conflict Resolution
### Merge Driver (Recommended)
Install the beads merge driver:
```bash
bd init # Prompts for merge driver setup
```
The driver automatically:
- Merges non-conflicting changes
- Preserves both sides for real conflicts
- Uses latest timestamp for same-issue edits
### Manual Resolution
```bash
# After merge conflict
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
bd sync
```
## Deletion Tracking
Deletions sync via `.beads/deletions.jsonl`:
```bash
# Delete issue
bd delete bd-42
# View deletions
bd deleted
bd deleted --since=30d
# Deletions propagate via git
git pull # Imports deletions from remote
```
## Best Practices
1. **Always sync at session end** - `bd sync`
2. **Install git hooks** - `bd hooks install`
3. **Use merge driver** - Avoids manual conflict resolution
4. **Check sync status** - `bd info` shows daemon/sync state

165
website/docs/core-concepts/daemon.md Normal file
View File

@@ -0,0 +1,165 @@
---
id: daemon
title: Daemon Architecture
sidebar_position: 3
---
# Daemon Architecture
Beads runs a background daemon for auto-sync and performance.
## Overview
Each workspace gets its own daemon process:
- Auto-starts on first `bd` command
- Handles database ↔ JSONL synchronization
- Listens on `.beads/bd.sock` (Unix) or `.beads/bd.pipe` (Windows)
- Version checking prevents mismatches after upgrades
## How It Works
```
CLI Command
↓
RPC to Daemon
↓
Daemon executes
↓
Auto-sync to JSONL (5s debounce)
```
Without daemon, commands access the database directly (slower, no auto-sync).
## Managing Daemons
```bash
# List all running daemons
bd daemons list
bd daemons list --json
# Check health and version mismatches
bd daemons health
bd daemons health --json
# View daemon logs
bd daemons logs . -n 100
# Restart all daemons
bd daemons killall
bd daemons killall --json
```
## Daemon Info
```bash
bd info
```
Shows:
- Daemon status (running/stopped)
- Daemon version vs CLI version
- Socket location
- Auto-sync status
## Disabling Daemon
Use `--no-daemon` flag to bypass the daemon:
```bash
bd --no-daemon ready
bd --no-daemon list
```
**When to disable:**
- Git worktrees (required)
- CI/CD pipelines
- Resource-constrained environments
- Debugging sync issues
## Event-Driven Mode (Experimental)
Event-driven mode replaces 5-second polling with instant reactivity:
```bash
# Enable globally
export BEADS_DAEMON_MODE=events
bd daemons killall # Restart to apply
```
**Benefits:**
- Less than 500ms latency (vs 5s polling)
- ~60% less CPU usage
- Instant sync after changes
**How to verify:**
```bash
bd info | grep "daemon mode"
```
## Troubleshooting
### Daemon not starting
```bash
# Check if socket exists
ls -la .beads/bd.sock
# Try direct mode
bd --no-daemon info
# Restart daemon
bd daemons killall
bd info
```
### Version mismatch
After upgrading bd:
```bash
bd daemons killall
bd info # Should show matching versions
```
### Sync not happening
```bash
# Force sync
bd sync
# Check daemon logs
bd daemons logs . -n 50
# Verify git status
git status .beads/
```
### Port/socket conflicts
```bash
# Kill all daemons
bd daemons killall
# Remove stale socket
rm -f .beads/bd.sock
# Restart
bd info
```
## Configuration
Daemon behavior can be configured:
```bash
# Set sync debounce interval
bd config set daemon.sync_interval 10s
# Disable auto-start
bd config set daemon.auto_start false
# Set log level
bd config set daemon.log_level debug
```
See [Configuration](/reference/configuration) for all options.

129
website/docs/core-concepts/hash-ids.md Normal file
View File

@@ -0,0 +1,129 @@
---
id: hash-ids
title: Hash-based IDs
sidebar_position: 5
---
# Hash-based IDs
Understanding beads' collision-resistant ID system.
## The Problem
Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and later merge
## The Solution
Beads uses hash-based IDs:
```
bd-a1b2c3 # Short hash
bd-f14c # Even shorter
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
```
**Properties:**
- Globally unique (content-based hash)
- No coordination needed between creators
- Merge-friendly across branches
- Predictable length (configurable)
## How Hashes Work
IDs are generated from:
- Issue title
- Creation timestamp
- Random salt
```bash
# Create issue - ID assigned automatically
bd create "Fix authentication bug"
# Returns: bd-7x2f
# The ID is deterministic for same content+timestamp
```
## Hierarchical IDs
For epics and subtasks:
```bash
# Parent epic
bd create "Auth System" -t epic
# Returns: bd-a3f8e9
# Children auto-increment
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
```
Benefits:
- Clear parent-child relationship
- No namespace collision (parent hash is unique)
- Up to 3 levels of nesting
## ID Configuration
Configure ID prefix and length:
```bash
# Set prefix (default: bd)
bd config set id.prefix myproject
# Set hash length (default: 4)
bd config set id.hash_length 6
# New issues use new format
bd create "Test"
# Returns: myproject-a1b2c3
```
## Collision Handling
While rare, collisions are handled automatically:
1. On import, if hash collision detected
2. Beads appends disambiguator
3. Both issues preserved
```bash
# Check for collisions
bd info --schema --json | jq '.collision_count'
```
## Working with IDs
```bash
# Partial ID matching
bd show a1b2 # Finds bd-a1b2...
bd show auth # Fuzzy match by title
# Full ID required for ambiguous cases
bd show bd-a1b2c3d4
# List with full IDs
bd list --full-ids
```
## Migration from Sequential IDs
If migrating from a system with sequential IDs:
```bash
# Import preserves original IDs in metadata
bd import -i old-issues.json
# View original ID
bd show bd-new --json | jq '.original_id'
```
## Best Practices
1. **Use short references** - `bd-a1b2` is usually unique enough
2. **Use `--json` for scripts** - Parse full ID programmatically
3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages
4. **Let hierarchies form naturally** - Create epics, add children as needed

76
website/docs/core-concepts/index.md Normal file
View File

@@ -0,0 +1,76 @@
---
id: index
title: Core Concepts
sidebar_position: 1
---
# Core Concepts
Understanding the fundamental concepts behind beads.
## Design Philosophy
Beads was built with these principles:
1. **Git as source of truth** - Issues sync via JSONL files, enabling collaboration across branches
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
3. **Local-first operation** - SQLite database for fast queries, background sync
4. **Declarative workflows** - Formulas define repeatable patterns
## Key Components
### Issues
Work items with:
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
- **Priority** - 0 (critical) to 4 (backlog)
- **Status** - `open`, `in_progress`, `closed`
- **Labels** - Flexible tagging
- **Dependencies** - Blocking relationships
### Dependencies
Four types of relationships:
| Type | Description | Affects Ready Queue |
|------|-------------|---------------------|
| `blocks` | Hard dependency (X blocks Y) | Yes |
| `parent-child` | Epic/subtask relationship | No |
| `discovered-from` | Track issues found during work | No |
| `related` | Soft relationship | No |
### Daemon
Background process per workspace:
- Auto-starts on first command
- Handles auto-sync with 5s debounce
- Socket at `.beads/bd.sock`
- Manage with `bd daemons` commands
### JSONL Sync
The synchronization mechanism:
```
SQLite DB (.beads/beads.db)
↕ auto-sync
JSONL (.beads/issues.jsonl)
↕ git
Remote repository
```
### Formulas
Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations
## Navigation
- [Issues & Dependencies](/core-concepts/issues)
- [Daemon Architecture](/core-concepts/daemon)
- [JSONL Sync](/core-concepts/jsonl-sync)
- [Hash-based IDs](/core-concepts/hash-ids)

183
website/docs/core-concepts/issues.md Normal file
View File

@@ -0,0 +1,183 @@
---
id: issues
title: Issues & Dependencies
sidebar_position: 2
---
# Issues & Dependencies
Understanding the issue model in beads.
## Issue Structure
Every issue has:
```bash
bd show bd-42 --json
```
```json
{
"id": "bd-42",
"title": "Implement authentication",
"description": "Add JWT-based auth",
"type": "feature",
"status": "open",
"priority": 1,
"labels": ["backend", "security"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
```
## Issue Types
| Type | Use Case |
|------|----------|
| `bug` | Something broken that needs fixing |
| `feature` | New functionality |
| `task` | Work item (tests, docs, refactoring) |
| `epic` | Large feature with subtasks |
| `chore` | Maintenance (dependencies, tooling) |
## Priorities
| Priority | Level | Examples |
|----------|-------|----------|
| 0 | Critical | Security, data loss, broken builds |
| 1 | High | Major features, important bugs |
| 2 | Medium | Nice-to-have features, minor bugs |
| 3 | Low | Polish, optimization |
| 4 | Backlog | Future ideas |
## Creating Issues
```bash
# Basic issue
bd create "Fix login bug" -t bug -p 1
# With description
bd create "Add password reset" \
--description="Users need to reset forgotten passwords via email" \
-t feature -p 2
# With labels
bd create "Update dependencies" -t chore -l "maintenance,security"
# JSON output for agents
bd create "Task" -t task --json
```
## Dependencies
### Blocking Dependencies
The `blocks` relationship affects the ready queue:
```bash
# Add dependency: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View dependencies
bd dep tree bd-2
# See blocked issues
bd blocked
# See ready work (not blocked)
bd ready
```
### Structural Relationships
These don't affect the ready queue:
```bash
# Parent-child (epic subtasks)
bd create "Epic" -t epic
bd create "Subtask" --parent bd-42
# Discovered-from (found during work)
bd create "Found bug" --deps discovered-from:bd-42
# Related (soft link)
bd relate bd-1 bd-2
```
### Dependency Types
| Type | Description | Ready Queue Impact |
|------|-------------|-------------------|
| `blocks` | Hard dependency | Yes - blocked items not ready |
| `parent-child` | Epic/subtask hierarchy | No |
| `discovered-from` | Tracks origin of discovery | No |
| `related` | Soft relationship | No |
## Hierarchical Issues
For large features, use hierarchical IDs:
```bash
# Create epic
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Child tasks auto-number
bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2
# View hierarchy
bd dep tree bd-a3f8e9
```
## Updating Issues
```bash
# Change status
bd update bd-42 --status in_progress
# Change priority
bd update bd-42 --priority 0
# Add labels
bd update bd-42 --add-label urgent
# Multiple changes
bd update bd-42 --status in_progress --priority 1 --add-label "in-review"
```
## Closing Issues
```bash
# Simple close
bd close bd-42
# With reason
bd close bd-42 --reason "Implemented in PR #123"
# JSON output
bd close bd-42 --json
```
## Searching and Filtering
```bash
# By status
bd list --status open
bd list --status in_progress
# By priority
bd list --priority 1
bd list --priority 0,1 # Multiple
# By type
bd list --type bug
bd list --type feature,task
# By label
bd list --label-any urgent,critical
bd list --label-all backend,security
# Combined filters
bd list --status open --priority 1 --type bug --json
```

179
website/docs/core-concepts/jsonl-sync.md Normal file
View File

@@ -0,0 +1,179 @@
---
id: jsonl-sync
title: JSONL Sync
sidebar_position: 4
---
# JSONL Sync
How beads synchronizes issues across git.
## The Magic
Beads uses a dual-storage architecture:
```
SQLite DB (.beads/beads.db, gitignored)
↕ auto-sync (5s debounce)
JSONL (.beads/issues.jsonl, git-tracked)
↕ git push/pull
Remote JSONL (shared across machines)
```
**Why this design?**
- SQLite for fast local queries
- JSONL for git-friendly versioning
- Automatic sync keeps them aligned
## Auto-Sync Behavior
### Export (SQLite → JSONL)
Triggers:
- Any database change
- After 5 second debounce (batches multiple changes)
- Manual `bd sync`
```bash
# Force immediate export
bd sync
# Check what would be exported
bd export --dry-run
```
### Import (JSONL → SQLite)
Triggers:
- After `git pull` (via git hooks)
- When JSONL is newer than database
- Manual `bd import`
```bash
# Force import
bd import -i .beads/issues.jsonl
# Preview import
bd import -i .beads/issues.jsonl --dry-run
```
## Git Hooks
Install hooks for seamless sync:
```bash
bd hooks install
```
Hooks installed:
- **pre-commit** - Exports to JSONL before commit
- **post-merge** - Imports from JSONL after pull
- **pre-push** - Ensures sync before push
## Manual Sync
```bash
# Full sync cycle: export + commit + push
bd sync
# Just export
bd export
# Just import
bd import -i .beads/issues.jsonl
```
## Conflict Resolution
When JSONL conflicts occur during git merge:
### With Merge Driver (Recommended)
The beads merge driver handles JSONL conflicts automatically:
```bash
# Install merge driver
bd init # Prompts for merge driver setup
```
The driver:
- Merges non-conflicting changes
- Preserves both sides for real conflicts
- Uses latest timestamp for same-issue edits
### Without Merge Driver
Manual resolution:
```bash
# After merge conflict
git checkout --ours .beads/issues.jsonl # or --theirs
bd import -i .beads/issues.jsonl
bd sync
```
## Orphan Handling
When importing issues with missing parents:
```bash
# Configure orphan handling
bd config set import.orphan_handling allow # Import anyway (default)
bd config set import.orphan_handling resurrect # Restore deleted parents
bd config set import.orphan_handling skip # Skip orphans
bd config set import.orphan_handling strict # Fail on orphans
```
Per-command override:
```bash
bd import -i issues.jsonl --orphan-handling resurrect
```
## Deletion Tracking
Deleted issues are tracked in `.beads/deletions.jsonl`:
```bash
# Delete issue (records to manifest)
bd delete bd-42
# View deletions
bd deleted
bd deleted --since=30d
# Deletions propagate via git
git pull # Imports deletions from remote
```
## Troubleshooting Sync
### JSONL out of sync
```bash
# Force full sync
bd sync
# Check sync status
bd info
```
### Import errors
```bash
# Check import status
bd import -i .beads/issues.jsonl --dry-run
# Allow orphans if needed
bd import -i .beads/issues.jsonl --orphan-handling allow
```
### Duplicate detection
```bash
# Find duplicates after import
bd duplicates
# Auto-merge duplicates
bd duplicates --auto-merge
```

156
website/docs/getting-started/ide-setup.md Normal file
View File

@@ -0,0 +1,156 @@
---
id: ide-setup
title: IDE Setup
sidebar_position: 3
---
# IDE Setup for AI Agents
Configure your IDE for optimal beads integration.
## Claude Code
The recommended approach for Claude Code:
```bash
# Setup Claude Code integration
bd setup claude
```
This installs:
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
- **PreCompact hook** - Ensures `bd sync` before context compaction
**How it works:**
1. SessionStart hook runs `bd prime` automatically
2. `bd prime` injects ~1-2k tokens of workflow context
3. You use `bd` CLI commands directly
4. Git hooks auto-sync the database
**Verify installation:**
```bash
bd setup claude --check
```
### Manual Setup
If you prefer manual configuration, add to your Claude Code hooks:
```json
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd sync"]
}
}
```
## Cursor IDE
```bash
# Setup Cursor integration
bd setup cursor
```
This creates `.cursor/rules/beads.mdc` with beads-aware rules.
**Verify:**
```bash
bd setup cursor --check
```
## Aider
```bash
# Setup Aider integration
bd setup aider
```
This creates/updates `.aider.conf.yml` with beads context.
**Verify:**
```bash
bd setup aider --check
```
## Context Injection with `bd prime`
All integrations use `bd prime` to inject context:
```bash
bd prime
```
This outputs a compact (~1-2k tokens) workflow reference including:
- Available commands
- Current project status
- Workflow patterns
- Best practices
**Why context efficiency matters:**
- Compute cost scales with tokens
- Latency increases with context size
- Models attend better to smaller, focused contexts
## MCP Server (Alternative)
For MCP-only environments (Claude Desktop, no shell access):
```bash
# Install MCP server
pip install beads-mcp
```
Add to Claude Desktop config:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**Trade-offs:**
- Works in MCP-only environments
- Higher context overhead (10-50k tokens for tool schemas)
- Additional latency from MCP protocol
See [MCP Server](/integrations/mcp-server) for detailed configuration.
## Git Hooks
Ensure git hooks are installed for auto-sync:
```bash
bd hooks install
```
This installs:
- **pre-commit** - Validates changes before commit
- **post-merge** - Imports changes after pull
- **pre-push** - Ensures sync before push
**Check hook status:**
```bash
bd info # Shows warnings if hooks are outdated
```
## Verifying Your Setup
Run a complete health check:
```bash
# Check version
bd version
# Check daemon
bd info
# Check hooks
bd hooks status
# Check editor integration
bd setup claude --check # or cursor, aider
```

209
website/docs/getting-started/installation.md Normal file
View File

@@ -0,0 +1,209 @@
---
id: installation
title: Installation
sidebar_position: 1
---
# Installing bd
Complete installation guide for all platforms.
## Quick Install (Recommended)
### Homebrew (macOS/Linux)
```bash
brew tap steveyegge/beads
brew install bd
```
**Why Homebrew?**
- Simple one-command install
- Automatic updates via `brew upgrade`
- No need to install Go
- Handles PATH setup automatically
### Quick Install Script (All Platforms)
```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```
The installer will:
- Detect your platform (macOS/Linux, amd64/arm64)
- Install via `go install` if Go is available
- Fall back to building from source if needed
- Guide you through PATH setup if necessary
## Platform-Specific Installation
### macOS
**Via Homebrew** (recommended):
```bash
brew tap steveyegge/beads
brew install bd
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
**From source**:
```bash
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
### Linux
**Via Homebrew** (works on Linux too):
```bash
brew tap steveyegge/beads
brew install bd
```
**Arch Linux** (AUR):
```bash
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### Windows 11
Beads 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/steveyegge/beads/main/install.ps1 | iex
```
**Via go install**:
```pwsh
go install github.com/steveyegge/beads/cmd/bd@latest
```
## IDE and Editor Integrations
### CLI + Hooks (Recommended)
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 bd
# 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 cursor # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider # Aider - creates .aider.conf.yml
```
**How it works:**
- Editor hooks/rules inject `bd prime` automatically on session start
- `bd prime` provides ~1-2k tokens of workflow context
- You use `bd` CLI commands directly
- Git hooks (installed by `bd init`) auto-sync the database
**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
### MCP Server (Alternative)
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"
}
}
}
```
## Verifying Installation
After installing, verify bd is working:
```bash
bd version
bd help
```
## Troubleshooting
### `bd: command not found`
bd is not in your PATH:
```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"
```
### `zsh: killed bd` or crashes on macOS
This is typically caused by CGO/SQLite compatibility issues:
```bash
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```
## Updating bd
### Homebrew
```bash
brew upgrade bd
```
### go install
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
## Next Steps
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)

155
website/docs/getting-started/quickstart.md Normal file
View File

@@ -0,0 +1,155 @@
---
id: quickstart
title: Quick Start
sidebar_position: 2
---
# Beads Quick Start
Get up and running with Beads in 2 minutes.
## Initialize
First time in a repository:
```bash
# Basic setup
bd init
# For AI agents (non-interactive)
bd init --quiet
# OSS contributor (fork workflow)
bd init --contributor
# Team member (branch workflow)
bd init --team
# Protected main branch (GitHub/GitLab)
bd init --branch beads-sync
```
The wizard will:
- Create `.beads/` directory and database
- Import existing issues from git (if any)
- Prompt to install git hooks (recommended)
- Prompt to configure git merge driver (recommended)
- Auto-start daemon for sync
## Your First Issues
```bash
# Create a few issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
# List them
bd list
```
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
## Hierarchical Issues (Epics)
For large features, use hierarchical IDs to organize work:
```bash
# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create child tasks (automatically get .1, .2, .3 suffixes)
bd create "Design login UI" -p 1 # bd-a3f8e9.1
bd create "Backend validation" -p 1 # bd-a3f8e9.2
bd create "Integration tests" -p 1 # bd-a3f8e9.3
# View hierarchy
bd dep tree bd-a3f8e9
```
Output:
```
Dependency tree for bd-a3f8e9:
> bd-a3f8e9: Auth System [epic] [P1] (open)
> bd-a3f8e9.1: Design login UI [P1] (open)
> bd-a3f8e9.2: Backend validation [P1] (open)
> bd-a3f8e9.3: Integration tests [P1] (open)
```
## Add Dependencies
```bash
# API depends on database
bd dep add bd-2 bd-1
# Auth depends on API
bd dep add bd-3 bd-2
# View the tree
bd dep tree bd-3
```
Output:
```
Dependency tree for bd-3:
> bd-3: Add authentication [P2] (open)
> bd-2: Create API [P2] (open)
> bd-1: Set up database [P1] (open)
```
## Find Ready Work
```bash
bd ready
```
Output:
```
Ready work (1 issues with no blockers):
1. [P1] bd-1: Set up database
```
Only bd-1 is ready because bd-2 and bd-3 are blocked!
## Work the Queue
```bash
# Start working on bd-1
bd update bd-1 --status in_progress
# Complete it
bd close bd-1 --reason "Database setup complete"
# Check ready work again
bd ready
```
Now bd-2 is ready!
## Track Progress
```bash
# See blocked issues
bd blocked
# View statistics
bd stats
```
## Database Location
By default, the database is in `.beads/beads.db` (gitignored).
The JSONL file `.beads/issues.jsonl` is git-tracked and syncs automatically.
## Next Steps
- Add labels: `bd create "Task" -l "backend,urgent"`
- Filter ready work: `bd ready --priority 1`
- Search issues: `bd list --status open`
- Detect cycles: `bd dep cycles`
- See [CLI Reference](/cli-reference) for all commands

126
website/docs/getting-started/upgrading.md Normal file
View File

@@ -0,0 +1,126 @@
---
id: upgrading
title: Upgrading
sidebar_position: 4
---
# Upgrading bd
How to upgrade bd and keep your projects in sync.
## Checking for Updates
```bash
# Current version
bd version
# What's new in recent versions
bd info --whats-new
bd info --whats-new --json # Machine-readable
```
## Upgrading
### Homebrew
```bash
brew upgrade bd
```
### go install
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### From Source
```bash
cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
## After Upgrading
**Important:** After upgrading, update your hooks and restart daemons:
```bash
# 1. Check what changed
bd info --whats-new
# 2. Update git hooks to match new version
bd hooks install
# 3. Restart all daemons
bd daemons killall
# 4. Check for any outdated hooks
bd info # Shows warnings if hooks are outdated
```
**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.
## Database Migrations
After major upgrades, check for database migrations:
```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Preview migration changes
bd migrate --dry-run
# Apply migrations
bd migrate
# Migrate and clean up old files
bd migrate --cleanup --yes
```
## Daemon Version Mismatches
If you see daemon version mismatch warnings:
```bash
# List all running daemons
bd daemons list --json
# Check for version mismatches
bd daemons health --json
# Restart all daemons with new version
bd daemons killall --json
```
## Troubleshooting Upgrades
### Old daemon still running
```bash
bd daemons killall
```
### Hooks out of date
```bash
bd hooks install
```
### Database schema changed
```bash
bd migrate --dry-run
bd migrate
```
### Import errors after upgrade
Check the import configuration:
```bash
bd config get import.orphan_handling
bd import -i .beads/issues.jsonl --orphan-handling allow
```

120
website/docs/integrations/aider.md Normal file
View File

@@ -0,0 +1,120 @@
---
id: aider
title: Aider
sidebar_position: 3
---
# Aider Integration
How to use beads with Aider.
## Setup
### Quick Setup
```bash
bd setup aider
```
This creates/updates `.aider.conf.yml` with beads context.
### Verify Setup
```bash
bd setup aider --check
```
## Configuration
The setup adds to `.aider.conf.yml`:
```yaml
# Beads integration
read:
- .beads/issues.jsonl
# Optional: Auto-run bd prime
auto-commits: false
```
## Workflow
### Start Session
```bash
# Aider will have access to issues via .aider.conf.yml
aider
# Or manually inject context
bd prime | aider --message-file -
```
### During Work
Use bd commands alongside aider:
```bash
# In another terminal or after exiting aider
bd create "Found bug during work" --deps discovered-from:bd-42 --json
bd update bd-42 --status in_progress
bd ready
```
### End Session
```bash
bd sync
```
## Best Practices
1. **Keep issues visible** - Aider reads `.beads/issues.jsonl`
2. **Sync regularly** - Run `bd sync` after significant changes
3. **Use discovered-from** - Track issues found during work
4. **Document context** - Include descriptions in issues
## Example Workflow
```bash
# 1. Check ready work
bd ready
# 2. Start aider with issue context
aider --message "Working on bd-42: Fix auth bug"
# 3. Work in aider...
# 4. Create discovered issues
bd create "Found related bug" --deps discovered-from:bd-42 --json
# 5. Complete and sync
bd close bd-42 --reason "Fixed"
bd sync
```
## Troubleshooting
### Config not loading
```bash
# Check config exists
cat .aider.conf.yml
# Regenerate
bd setup aider
```
### Issues not visible
```bash
# Check JSONL exists
ls -la .beads/issues.jsonl
# Export if missing
bd export
```
## See Also
- [Claude Code](/integrations/claude-code)
- [IDE Setup](/getting-started/ide-setup)

186
website/docs/integrations/claude-code.md Normal file
View File

@@ -0,0 +1,186 @@
---
id: claude-code
title: Claude Code
sidebar_position: 1
---
# Claude Code Integration
How to use beads with Claude Code.
## Setup
### Quick Setup
```bash
bd setup claude
```
This installs:
- **SessionStart hook** - Runs `bd prime` on session start
- **PreCompact hook** - Runs `bd sync` before context compaction
### Manual Setup
Add to your Claude Code hooks configuration:
```json
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd sync"]
}
}
```
### Verify Setup
```bash
bd setup claude --check
```
## How It Works
1. **Session starts** → `bd prime` injects ~1-2k tokens of context
2. **You work** → Use `bd` CLI commands directly
3. **Session compacts** → `bd sync` saves work to git
4. **Session ends** → Changes synced via git
## Essential Commands for Agents
### Creating Issues
```bash
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
```
### Working on Issues
```bash
# Find ready work
bd ready --json
# Start work
bd update bd-42 --status in_progress --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```
### Querying
```bash
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
```
### Syncing
```bash
# ALWAYS run at session end
bd sync
```
## Best Practices
### Always Use `--json`
```bash
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
```
### Always Include Descriptions
```bash
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```
### Link Related Work
```bash
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Sync Before Session End
```bash
# ALWAYS run before ending
bd sync
```
## Plugin (Optional)
For enhanced UX with slash commands:
```bash
# In Claude Code
/plugin marketplace add steveyegge/beads
/plugin install beads
# Restart Claude Code
```
Adds slash commands:
- `/bd-ready` - Show ready work
- `/bd-create` - Create issue
- `/bd-show` - Show issue
- `/bd-update` - Update issue
- `/bd-close` - Close issue
## Troubleshooting
### Context not injected
```bash
# Check hook setup
bd setup claude --check
# Manually prime
bd prime
```
### Changes not syncing
```bash
# Force sync
bd sync
# Check daemon
bd info
bd daemons health
```
### Database not found
```bash
# Initialize beads
bd init --quiet
```
## See Also
- [MCP Server](/integrations/mcp-server) - For MCP-only environments
- [IDE Setup](/getting-started/ide-setup) - Other editors

149
website/docs/integrations/mcp-server.md Normal file
View File

@@ -0,0 +1,149 @@
---
id: mcp-server
title: MCP Server
sidebar_position: 2
---
# MCP Server
Use beads in MCP-only environments.
## When to Use MCP
Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments
**Prefer CLI + hooks** when shell is available - it's more context efficient.
## Installation
### Using uv (Recommended)
```bash
uv tool install beads-mcp
```
### Using pip
```bash
pip install beads-mcp
```
## Configuration
### Claude Desktop (macOS)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
### Claude Desktop (Windows)
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
### Sourcegraph Amp
Add to MCP settings:
```json
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
## Available Tools
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 |
## Usage
Once configured, use naturally:
```
Create an issue for fixing the login bug with priority 1
```
The MCP server translates to appropriate `bd` commands.
## Trade-offs
| Aspect | CLI + Hooks | MCP Server |
|--------|-------------|------------|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |
## Troubleshooting
### Server won't start
Check if `beads-mcp` is in PATH:
```bash
which beads-mcp
```
If not found:
```bash
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
```
### Tools not appearing
1. Restart Claude Desktop
2. Check MCP config JSON syntax
3. Verify server path
### Permission errors
```bash
# Check directory permissions
ls -la .beads/
# Initialize if needed
bd init --quiet
```
## See Also
- [Claude Code](/integrations/claude-code) - CLI integration
- [Installation](/getting-started/installation) - Full install guide

87
website/docs/intro.md Normal file
View File

@@ -0,0 +1,87 @@
---
id: intro
title: Introduction
sidebar_position: 1
slug: /
---
# Beads Documentation
**Beads** (`bd`) is a git-backed issue tracker designed for AI-supervised coding workflows.
## Why Beads?
Traditional issue trackers (Jira, GitHub Issues) weren't designed for AI agents. Beads was built from the ground up for:
- **AI-native workflows** - Hash-based IDs prevent collisions when multiple agents work concurrently
- **Git-backed storage** - Issues sync via JSONL files, enabling collaboration across branches
- **Dependency-aware execution** - `bd ready` shows only unblocked work
- **Formula system** - Declarative templates for repeatable workflows
- **Multi-agent coordination** - Routing, gates, and molecules for complex workflows
## Quick Start
```bash
# Install via Homebrew (macOS/Linux)
brew tap steveyegge/beads
brew install bd
# Initialize in your project
cd your-project
bd init --quiet
# Create your first issue
bd create "Set up database" -p 1 -t task
# See ready work
bd ready
```
## Core Concepts
| Concept | Description |
|---------|-------------|
| **Issues** | Work items with priorities, types, labels, and dependencies |
| **Dependencies** | `blocks`, `parent-child`, `discovered-from`, `related` |
| **Daemon** | Background process for auto-sync and performance |
| **Formulas** | Declarative workflow templates (TOML or JSON) |
| **Molecules** | Work graphs with parent-child relationships |
| **Gates** | Async coordination primitives (human, timer, GitHub) |
## For AI Agents
Beads is optimized for AI coding agents:
```bash
# Always use --json for programmatic access
bd list --json
bd show bd-42 --json
# Track discovered work during implementation
bd create "Found bug in auth" --description="Details..." \
--deps discovered-from:bd-100 --json
# Sync at end of session
bd sync
```
See the [Claude Code integration](/integrations/claude-code) for detailed agent instructions.
## Architecture
```
SQLite DB (.beads/beads.db, gitignored)
↕ auto-sync (5s debounce)
JSONL (.beads/issues.jsonl, git-tracked)
↕ git push/pull
Remote JSONL (shared across machines)
```
The magic is automatic synchronization between a local SQLite database and git-tracked JSONL files.
## Next Steps
- [Installation](/getting-started/installation) - Get bd installed
- [Quick Start](/getting-started/quickstart) - Create your first issues
- [CLI Reference](/cli-reference) - All available commands
- [Workflows](/workflows) - Formulas, molecules, and gates

157
website/docs/multi-agent/coordination.md Normal file
View File

@@ -0,0 +1,157 @@
---
id: coordination
title: Agent Coordination
sidebar_position: 3
---
# Agent Coordination
Patterns for coordinating work between multiple AI agents.
## Work Assignment
### Pinning Work
Assign work to a specific agent:
```bash
# Pin issue to agent
bd pin bd-42 --for agent-1
# Pin and start work
bd pin bd-42 --for agent-1 --start
# Unpin work
bd unpin bd-42
```
### Checking Pinned Work
```bash
# What's on my hook?
bd hook
# What's on agent-1's hook?
bd hook --agent agent-1
# JSON output
bd hook --json
```
## Handoff Patterns
### Sequential Handoff
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
# Agent B picks up
bd hook # Sees bd-42
bd update bd-42 --status in_progress
```
### Parallel Work
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
# Each agent works independently
# Coordinator monitors progress
bd list --status in_progress --json
```
### Fan-Out / Fan-In
Split work, then merge:
```bash
# Fan-out
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
# Fan-in: wait for all parts
bd dep add bd-merge bd-epic.1 bd-epic.2 bd-epic.3
```
## Agent Discovery
Find available agents:
```bash
# List known agents (if using agent registry)
bd agents list
# Check agent status
bd agents status agent-1
```
## Conflict Prevention
### File Reservations
Prevent concurrent edits:
```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
```
### Issue Locking
```bash
# Lock issue for exclusive work
bd lock bd-42 --for agent-1
# Unlock when done
bd unlock bd-42
```
## Communication Patterns
### Via Comments
```bash
# Agent A leaves note
bd comment add bd-42 "Completed API, needs frontend integration"
# Agent B reads
bd show bd-42 --full
```
### Via Labels
```bash
# Mark for review
bd update bd-42 --add-label "needs-review"
# Agent B filters
bd list --label-any needs-review
```
## Best Practices
1. **Clear ownership** - Always pin work to specific agent
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
5. **Monitor progress** - Regular status checks

72
website/docs/multi-agent/index.md Normal file
View File

@@ -0,0 +1,72 @@
---
id: index
title: Multi-Agent
sidebar_position: 1
---
# Multi-Agent Coordination
Beads supports coordination between multiple AI agents and repositories.
## Overview
Multi-agent features enable:
- **Routing** - Automatic issue routing to correct repositories
- **Cross-repo dependencies** - Dependencies across repository boundaries
- **Agent coordination** - Work assignment and handoff between agents
## Key Concepts
### Routes
Routes define which repository handles which issues:
```jsonl
{"pattern": "frontend/*", "target": "frontend-repo"}
{"pattern": "backend/*", "target": "backend-repo"}
{"pattern": "*", "target": "main-repo"}
```
### Work Assignment
Pin work to specific agents:
```bash
bd pin bd-42 --for agent-1 --start
bd hook --agent agent-1 # Show pinned work
```
### Cross-repo Dependencies
Track dependencies across repositories:
```bash
bd dep add bd-42 external:other-repo/bd-100
```
## Architecture
```
┌─────────────────┐
│ Main Repo │
│ (coordinator) │
└────────┬────────┘
│ routes
┌────┴────┐
│ │
┌───▼───┐ ┌───▼───┐
│Frontend│ │Backend│
│ Repo │ │ Repo │
└────────┘ └────────┘
```
## Getting Started
1. **Single repo**: Standard beads workflow
2. **Multi-repo**: Configure routes and cross-repo deps
3. **Multi-agent**: Add work assignment and handoff
## Navigation
- [Routing](/multi-agent/routing) - Auto-routing configuration
- [Coordination](/multi-agent/coordination) - Agent coordination patterns

116
website/docs/multi-agent/routing.md Normal file
View File

@@ -0,0 +1,116 @@
---
id: routing
title: Routing
sidebar_position: 2
---
# Multi-Repo Routing
Automatic issue routing across repositories.
## Overview
Routing enables:
- Issues created in one repo routed to another
- Pattern-based routing rules
- Fallback to default repository
## Configuration
Create `.beads/routes.jsonl`:
```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}
```
## Route Fields
| Field | Description |
|-------|-------------|
| `pattern` | Glob pattern to match |
| `target` | Target repository |
| `priority` | Higher = checked first |
## 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
```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/**"
```
## Auto-Routing
When creating issues, beads checks routes:
```bash
bd create "Fix frontend button alignment" -t bug
# Auto-routed to frontend-repo based on title match
```
Override with explicit target:
```bash
bd create "Fix button" --repo backend-repo
```
## Cross-Repo Dependencies
Track dependencies across repos:
```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
```
## Hydration
Pull related issues from other repos:
```bash
# Hydrate issues from related repos
bd hydrate
# Preview hydration
bd hydrate --dry-run
# Hydrate specific repo
bd hydrate --from backend-repo
```
## Best Practices
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

62
website/docs/recovery/circular-dependencies.md Normal file
View File

@@ -0,0 +1,62 @@
---
sidebar_position: 4
title: Circular Dependencies
description: Detect and break dependency cycles
---
# Circular Dependencies Recovery
This runbook helps you detect and break circular dependency cycles in your issues.
## Symptoms
- "circular dependency detected" errors
- `bd blocked` shows unexpected results
- Issues that should be ready appear blocked
## Diagnosis
```bash
# Check for blocked issues
bd blocked
# View dependencies for a specific issue
bd show <issue-id>
# List all dependencies
bd dep tree
```
## Solution
**Step 1:** Identify the cycle
```bash
bd blocked --verbose
```
**Step 2:** Map the dependency chain
```bash
bd show <issue-a>
bd show <issue-b>
# Follow the chain until you return to <issue-a>
```
**Step 3:** Determine which dependency to remove
Consider: Which dependency is least critical to the workflow?
**Step 4:** Remove the problematic dependency
```bash
bd dep remove <dependent-issue> <blocking-issue>
```
**Step 5:** Verify the cycle is broken
```bash
bd blocked
bd ready
```
## Prevention
- Think "X needs Y" not "X before Y" when adding dependencies
- Use `bd blocked` after adding dependencies to check for cycles
- Keep dependency chains shallow when possible

66
website/docs/recovery/database-corruption.md Normal file
View File

@@ -0,0 +1,66 @@
---
sidebar_position: 2
title: Database Corruption
description: Recover from SQLite database corruption
---
# Database Corruption Recovery
This runbook helps you recover from SQLite database corruption in Beads.
## Symptoms
- SQLite error messages during `bd` commands
- "database is locked" errors that persist
- Missing issues that should exist
- Inconsistent state between JSONL and database
## Diagnosis
```bash
# Check database integrity
bd status
# Look for corruption indicators
ls -la .beads/beads.db*
```
If you see `-wal` or `-shm` files alongside `beads.db`, a transaction may have been interrupted.
## Solution
:::warning
Back up your `.beads/` directory before proceeding.
:::
**Step 1:** Stop the daemon
```bash
bd daemon stop
```
**Step 2:** Back up current state
```bash
cp -r .beads .beads.backup
```
**Step 3:** Rebuild from JSONL (source of truth)
```bash
bd doctor --fix
```
**Step 4:** Verify recovery
```bash
bd status
bd list
```
**Step 5:** Restart daemon
```bash
bd daemon start
```
## Prevention
- Avoid interrupting `bd sync` operations
- Let the daemon handle synchronization
- Use `bd daemon stop` before system shutdown

45
website/docs/recovery/index.md Normal file
View File

@@ -0,0 +1,45 @@
---
sidebar_position: 1
title: Recovery Overview
description: Diagnose and resolve common Beads issues
---
# Recovery Overview
This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention.
## Common Issues
| Issue | Symptoms | Runbook |
|-------|----------|---------|
| Database Corruption | SQLite errors, missing data | [Database Corruption](/recovery/database-corruption) |
| Merge Conflicts | JSONL conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
| Circular Dependencies | Cycle detection errors | [Circular Dependencies](/recovery/circular-dependencies) |
| Sync Failures | `bd sync` errors | [Sync Failures](/recovery/sync-failures) |
## Quick Diagnostic
Before diving into specific runbooks, try these quick checks:
```bash
# Check Beads status
bd status
# Verify daemon is running
bd daemon status
# Check for blocked issues
bd blocked
```
:::tip
Most issues can be diagnosed with `bd status`. Start there before following specific runbooks.
:::
## Getting Help
If these runbooks don't resolve your issue:
1. Check the [FAQ](/reference/faq)
2. Search [existing issues](https://github.com/steveyegge/beads/issues)
3. Open a new issue with diagnostic output

65
website/docs/recovery/merge-conflicts.md Normal file
View File

@@ -0,0 +1,65 @@
---
sidebar_position: 3
title: Merge Conflicts
description: Resolve JSONL merge conflicts
---
# Merge Conflicts Recovery
This runbook helps you resolve JSONL merge conflicts that occur during Git operations.
## Symptoms
- Git merge conflicts in `.beads/*.jsonl` files
- `bd sync` fails with conflict errors
- Different issue states between clones
## Diagnosis
```bash
# Check for conflicted files
git status
# Look for conflict markers
grep -l "<<<<<<" .beads/*.jsonl
```
## Solution
:::warning
JSONL files are append-only logs. Manual editing requires care.
:::
**Step 1:** Identify conflicted files
```bash
git diff --name-only --diff-filter=U
```
**Step 2:** For each conflicted JSONL file, keep both versions
```bash
# Accept both changes (append-only is safe)
git checkout --ours .beads/issues.jsonl
git add .beads/issues.jsonl
```
**Step 3:** Force rebuild to reconcile
```bash
bd doctor --fix
```
**Step 4:** Verify state
```bash
bd list
bd status
```
**Step 5:** Complete the merge
```bash
git commit -m "Resolved beads merge conflicts"
```
## Prevention
- Sync before and after Git operations
- Use `bd sync` regularly
- Avoid concurrent modifications from multiple clones

74
website/docs/recovery/sync-failures.md Normal file
View File

@@ -0,0 +1,74 @@
---
sidebar_position: 5
title: Sync Failures
description: Recover from bd sync failures
---
# Sync Failures Recovery
This runbook helps you recover from `bd sync` failures.
## Symptoms
- `bd sync` hangs or times out
- Network-related error messages
- "failed to push" or "failed to pull" errors
- Daemon not responding
## Diagnosis
```bash
# Check daemon status
bd daemon status
# Check sync state
bd status
# View daemon logs
cat .beads/daemon.log | tail -50
```
## Solution
**Step 1:** Stop the daemon
```bash
bd daemon stop
```
**Step 2:** Check for lock files
```bash
ls -la .beads/*.lock
# Remove stale locks if daemon is definitely stopped
rm -f .beads/*.lock
```
**Step 3:** Force a fresh sync
```bash
bd doctor --fix
```
**Step 4:** Restart daemon
```bash
bd daemon start
```
**Step 5:** Verify sync works
```bash
bd sync
bd status
```
## Common Causes
| Cause | Solution |
|-------|----------|
| Network timeout | Retry with better connection |
| Stale lock file | Remove lock after stopping daemon |
| Corrupted state | Use `bd doctor --fix` |
| Git conflicts | See [Merge Conflicts](/recovery/merge-conflicts) |
## Prevention
- Ensure stable network before sync
- Let sync complete before closing terminal
- Use `bd daemon stop` before system shutdown

176
website/docs/reference/advanced.md Normal file
View File

@@ -0,0 +1,176 @@
---
id: advanced
title: Advanced Features
sidebar_position: 3
---
# Advanced Features
Advanced beads functionality.
## Issue Rename
Rename issues while preserving references:
```bash
bd rename bd-42 bd-new-id
bd rename bd-42 bd-new-id --dry-run # Preview
```
Updates:
- All dependencies pointing to old ID
- All references in other issues
- Comments and descriptions
## Issue Merge
Merge duplicate issues:
```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run
```
What gets merged:
- Dependencies → target
- Text references updated across all issues
- Source issues closed with merge reason
## Database Compaction
Reduce database size by compacting old issues:
```bash
# View compaction statistics
bd admin compact --stats
# Preview candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediate deletion (CAUTION!)
bd admin cleanup --force
```
**When to compact:**
- Database > 10MB with old closed issues
- After major milestones
- Before archiving project phase
## Restore from History
View deleted or compacted issues from git:
```bash
bd restore bd-42 --show
bd restore bd-42 --to-file issue.json
```
## Database Inspection
```bash
# Schema info
bd info --schema --json
# Raw database query (advanced)
sqlite3 .beads/beads.db "SELECT * FROM issues LIMIT 5"
```
## Custom Tables
Extend the database with custom tables:
```go
// In Go code using beads as library
storage.UnderlyingDB().Exec(`
CREATE TABLE IF NOT EXISTS custom_table (...)
`)
```
See [EXTENDING.md](https://github.com/steveyegge/beads/blob/main/docs/EXTENDING.md).
## Event System
Subscribe to beads events:
```bash
# View recent events
bd events list --since 1h
# Watch events in real-time
bd events watch
```
Events:
- `issue.created`
- `issue.updated`
- `issue.closed`
- `dependency.added`
- `sync.completed`
## Batch Operations
### Create Multiple
```bash
cat issues.jsonl | bd import -i -
```
### Update Multiple
```bash
bd list --status open --priority 4 --json | \
jq -r '.[].id' | \
xargs -I {} bd update {} --priority 3
```
### Close Multiple
```bash
bd list --label "sprint-1" --status open --json | \
jq -r '.[].id' | \
xargs -I {} bd close {} --reason "Sprint complete"
```
## API Access
Use beads as a Go library:
```go
import "github.com/steveyegge/beads/internal/storage"
db, _ := storage.NewSQLite(".beads/beads.db")
issues, _ := db.ListIssues(storage.ListOptions{
Status: "open",
})
```
## Performance Tuning
### Large Databases
```bash
# Enable WAL mode
bd config set database.wal_mode true
# Increase cache
bd config set database.cache_size 10000
```
### Many Concurrent Agents
```bash
# Use event-driven daemon
export BEADS_DAEMON_MODE=events
bd daemons killall
```
### CI/CD Optimization
```bash
# Disable daemon in CI
export BEADS_NO_DAEMON=true
bd --no-daemon list
```

161
website/docs/reference/configuration.md Normal file
View File

@@ -0,0 +1,161 @@
---
id: configuration
title: Configuration
sidebar_position: 1
---
# Configuration
Complete configuration reference for beads.
## Configuration Locations
1. **Project config**: `.beads/config.toml` (highest priority)
2. **User config**: `~/.beads/config.toml`
3. **Environment variables**: `BEADS_*`
4. **Command-line flags**: (highest priority)
## Managing Configuration
```bash
# Get config value
bd config get import.orphan_handling
# Set config value
bd config set import.orphan_handling allow
# List all config
bd config list
# Reset to default
bd config reset import.orphan_handling
```
## Configuration Options
### Database
```toml
[database]
path = ".beads/beads.db" # Database file location
```
### ID Generation
```toml
[id]
prefix = "bd" # Issue ID prefix
hash_length = 4 # Hash length in IDs
```
### Import
```toml
[import]
orphan_handling = "allow" # allow|resurrect|skip|strict
dedupe_on_import = false # Run duplicate detection after import
```
| Mode | Behavior |
|------|----------|
| `allow` | Import orphans without validation (default) |
| `resurrect` | Restore deleted parents as tombstones |
| `skip` | Skip orphaned children with warning |
| `strict` | Fail if parent missing |
### Export
```toml
[export]
path = ".beads/issues.jsonl" # Export file location
auto_export = true # Auto-export on changes
debounce_seconds = 5 # Debounce interval
```
### Daemon
```toml
[daemon]
auto_start = true # Auto-start daemon
sync_interval = "5s" # Sync check interval
log_level = "info" # debug|info|warn|error
mode = "poll" # poll|events (experimental)
```
### Git
```toml
[git]
auto_commit = true # Auto-commit on sync
auto_push = true # Auto-push on sync
commit_message = "bd sync" # Default commit message
```
### Hooks
```toml
[hooks]
pre_commit = true # Enable pre-commit hook
post_merge = true # Enable post-merge hook
pre_push = true # Enable pre-push hook
```
### Deletions
```toml
[deletions]
retention_days = 30 # Keep deletion records for N days
prune_on_sync = true # Auto-prune old records
```
## Environment Variables
| Variable | Description |
|----------|-------------|
| `BEADS_DB` | Database path |
| `BEADS_NO_DAEMON` | Disable daemon |
| `BEADS_DAEMON_MODE` | Daemon mode (poll/events) |
| `BEADS_LOG_LEVEL` | Log level |
| `BEADS_CONFIG` | Config file path |
## Per-Command Override
```bash
# Override database
bd --db /tmp/test.db list
# Disable daemon for single command
bd --no-daemon create "Task"
```
## Example Configuration
`.beads/config.toml`:
```toml
[id]
prefix = "myproject"
hash_length = 6
[import]
orphan_handling = "resurrect"
dedupe_on_import = true
[daemon]
auto_start = true
sync_interval = "10s"
mode = "events"
[git]
auto_commit = true
auto_push = true
[deletions]
retention_days = 90
```
## Viewing Active Configuration
```bash
bd info --json | jq '.config'
```

163
website/docs/reference/faq.md Normal file
View File

@@ -0,0 +1,163 @@
---
id: faq
title: FAQ
sidebar_position: 5
---
# Frequently Asked Questions
## General
### 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
- **Git-backed storage** enables branch-based workflows
- **Dependency-aware** ready queue for automated work selection
- **Formula system** for declarative workflow templates
### What does "beads" stand for?
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.
## Architecture
### Why SQLite + JSONL instead of just one?
- **SQLite** for fast local queries and complex filtering
- **JSONL** for git-friendly versioning and sync
- Auto-sync keeps them aligned
### 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
Hash-based IDs are globally unique without coordination.
### Why a daemon?
The daemon provides:
- Auto-sync with 5-second debounce
- Batched operations for performance
- Background monitoring
Use `--no-daemon` when not needed (CI, worktrees).
## Usage
### How do I sync issues to git?
```bash
# Auto-sync via daemon (default)
# Or manual sync:
bd sync
```
### How do I handle merge conflicts?
Install the beads merge driver:
```bash
bd init # Prompts for merge driver
```
Or manually resolve and reimport.
### 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
### How do I use beads in CI/CD?
```bash
# Disable daemon in CI
export BEADS_NO_DAEMON=true
# Or per-command
bd --no-daemon list
```
## Workflows
### What are formulas?
Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).
### What are gates?
Async coordination primitives:
- Human gates wait for approval
- Timer gates wait for duration
- GitHub gates wait for CI/PR events
### 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
## Integration
### Should I use CLI or MCP?
**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.):
- Lower context overhead (~1-2k vs 10-50k tokens)
- Faster execution
- Universal across editors
**Use MCP** when CLI unavailable (Claude Desktop).
### How do I integrate with my editor?
```bash
bd setup claude # Claude Code
bd setup cursor # Cursor
bd setup aider # Aider
```
### Can beads import from GitHub Issues?
Yes:
```bash
bd import --from github --repo owner/repo
```
## Troubleshooting
### Why is the daemon not starting?
```bash
# Remove stale socket
rm -f .beads/bd.sock
# Restart
bd daemons killall
bd info
```
### Why aren't my changes syncing?
```bash
# Check daemon status
bd info
# Force sync
bd sync
# Check hooks
bd hooks status
```
### How do I report a bug?
1. Check existing issues: https://github.com/steveyegge/beads/issues
2. Include: `bd version`, `bd info --json`, reproduction steps
3. File at: https://github.com/steveyegge/beads/issues/new

170
website/docs/reference/git-integration.md Normal file
View File

@@ -0,0 +1,170 @@
---
id: git-integration
title: Git Integration
sidebar_position: 2
---
# Git Integration
How beads integrates with git.
## Overview
Beads uses git for:
- **JSONL sync** - Issues stored in `.beads/issues.jsonl`
- **Deletion tracking** - `.beads/deletions.jsonl`
- **Conflict resolution** - Custom merge driver
- **Hooks** - Auto-sync on git operations
## File Structure
```
.beads/
├── beads.db # SQLite database (gitignored)
├── issues.jsonl # Issue data (git-tracked)
├── deletions.jsonl # Deletion manifest (git-tracked)
├── config.toml # Project config (git-tracked)
└── bd.sock # Daemon socket (gitignored)
```
## Git Hooks
### Installation
```bash
bd hooks install
```
Installs:
- **pre-commit** - Exports database to JSONL
- **post-merge** - Imports from JSONL after pull
- **pre-push** - Ensures sync before push
### Status
```bash
bd hooks status
```
### Uninstall
```bash
bd hooks uninstall
```
## Merge Driver
### Purpose
The beads merge driver handles JSONL conflicts automatically:
- Merges non-conflicting changes
- Uses latest timestamp for same-issue edits
- Preserves both sides for real conflicts
### Installation
```bash
bd init # Prompts for merge driver setup
```
Or manually add to `.gitattributes`:
```gitattributes
.beads/issues.jsonl merge=beads
.beads/deletions.jsonl merge=beads
```
And `.git/config`:
```ini
[merge "beads"]
name = Beads JSONL merge driver
driver = bd merge-driver %O %A %B
```
## Protected Branches
For protected main branches:
```bash
bd init --branch beads-sync
```
This:
- Creates a separate `beads-sync` branch
- Syncs issues to that branch
- Avoids direct commits to main
## Git Worktrees
Beads requires `--no-daemon` in git worktrees:
```bash
# In worktree
bd --no-daemon create "Task"
bd --no-daemon list
```
Why: Daemon uses `.beads/bd.sock` which conflicts across worktrees.
## Branch Workflows
### Feature Branch
```bash
git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd sync
git push
```
### Fork Workflow
```bash
# In fork
bd init --contributor
# Work in separate planning repo...
bd sync
```
### Team Workflow
```bash
bd init --team
# All team members share issues.jsonl
git pull # Auto-imports via hook
```
## Conflict Resolution
### With Merge Driver
Automatic - driver handles most conflicts.
### Manual Resolution
```bash
# After conflict
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
bd sync
git add .beads/
git commit
```
### Duplicate Detection
After merge:
```bash
bd duplicates --auto-merge
```
## Best Practices
1. **Install hooks** - `bd hooks install`
2. **Use merge driver** - Avoid manual conflict resolution
3. **Sync regularly** - `bd sync` at session end
4. **Pull before work** - Get latest issues
5. **Use `--no-daemon` in worktrees**

233
website/docs/reference/troubleshooting.md Normal file
View File

@@ -0,0 +1,233 @@
---
id: troubleshooting
title: Troubleshooting
sidebar_position: 4
---
# Troubleshooting
Common issues and solutions.
## Installation Issues
### `bd: command not found`
```bash
# Check if installed
which bd
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
```
### `zsh: killed bd` on macOS
CGO/SQLite compatibility issue:
```bash
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```
### Permission denied
```bash
chmod +x $(which bd)
```
## Database Issues
### Database not found
```bash
# Initialize beads
bd init --quiet
# Or specify database
bd --db .beads/beads.db list
```
### Database locked
```bash
# Stop daemon
bd daemons killall
# Try again
bd list
```
### Corrupted database
```bash
# Restore from JSONL
rm .beads/beads.db
bd import -i .beads/issues.jsonl
```
## Daemon Issues
### Daemon not starting
```bash
# Check status
bd info
# Remove stale socket
rm -f .beads/bd.sock
# Restart
bd daemons killall
bd info
```
### Version mismatch
After upgrading bd:
```bash
bd daemons killall
bd info
```
### High CPU usage
```bash
# Switch to event-driven mode
export BEADS_DAEMON_MODE=events
bd daemons killall
```
## Sync Issues
### Changes not syncing
```bash
# Force sync
bd sync
# Check daemon
bd info | grep daemon
# Check hooks
bd hooks status
```
### Import errors
```bash
# Allow orphans
bd import -i .beads/issues.jsonl --orphan-handling allow
# Check for duplicates after
bd duplicates
```
### Merge conflicts
```bash
# Use merge driver
bd init # Setup merge driver
# Or manual resolution
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
bd sync
```
## Git Hook Issues
### Hooks not running
```bash
# Check if installed
ls -la .git/hooks/
# Reinstall
bd hooks install
```
### Hook errors
```bash
# Check hook script
cat .git/hooks/pre-commit
# Run manually
.git/hooks/pre-commit
```
## Dependency Issues
### Circular dependencies
```bash
# Detect cycles
bd dep cycles
# Remove one dependency
bd dep remove bd-A bd-B
```
### Missing dependencies
```bash
# Check orphan handling
bd config get import.orphan_handling
# Allow orphans
bd config set import.orphan_handling allow
```
## Performance Issues
### Slow queries
```bash
# Check database size
ls -lh .beads/beads.db
# Compact if large
bd admin compact --analyze
```
### High memory usage
```bash
# Reduce cache
bd config set database.cache_size 1000
```
## Getting Help
### Debug output
```bash
bd --verbose list
```
### Logs
```bash
bd daemons logs . -n 100
```
### System info
```bash
bd info --json
```
### File an issue
```bash
# Include this info
bd version
bd info --json
uname -a
```
Report at: https://github.com/steveyegge/beads/issues

252
website/docs/workflows/formulas.md Normal file
View File

@@ -0,0 +1,252 @@
---
id: formulas
title: Formulas
sidebar_position: 3
---
# Formulas
Formulas are declarative workflow templates.
## Formula Format
Formulas can be written in TOML (preferred) or JSON:
### TOML Format
```toml
formula = "feature-workflow"
description = "Standard feature development workflow"
version = 1
type = "workflow"
[vars.feature_name]
description = "Name of the feature"
required = true
[[steps]]
id = "design"
title = "Design {{feature_name}}"
type = "human"
description = "Create design document"
[[steps]]
id = "implement"
title = "Implement {{feature_name}}"
needs = ["design"]
[[steps]]
id = "review"
title = "Code review"
needs = ["implement"]
type = "human"
[[steps]]
id = "merge"
title = "Merge to main"
needs = ["review"]
```
### JSON Format
```json
{
"formula": "feature-workflow",
"description": "Standard feature development workflow",
"version": 1,
"type": "workflow",
"vars": {
"feature_name": {
"description": "Name of the feature",
"required": true
}
},
"steps": [
{
"id": "design",
"title": "Design {{feature_name}}",
"type": "human"
},
{
"id": "implement",
"title": "Implement {{feature_name}}",
"needs": ["design"]
}
]
}
```
## Formula Types
| Type | Description |
|------|-------------|
| `workflow` | Standard step sequence |
| `expansion` | Template for expansion operator |
| `aspect` | Cross-cutting concerns |
## Variables
Define variables with defaults and constraints:
```toml
[vars.version]
description = "Release version"
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"
[vars.environment]
description = "Target environment"
default = "staging"
enum = ["staging", "production"]
```
Use variables in steps:
```toml
[[steps]]
title = "Deploy {{version}} to {{environment}}"
```
## Step Types
| Type | Description |
|------|-------------|
| `task` | Normal work step (default) |
| `human` | Requires human action |
| `gate` | Async coordination point |
## Dependencies
### Sequential
```toml
[[steps]]
id = "step1"
title = "First step"
[[steps]]
id = "step2"
title = "Second step"
needs = ["step1"]
```
### Parallel then Join
```toml
[[steps]]
id = "test-unit"
title = "Unit tests"
[[steps]]
id = "test-integration"
title = "Integration tests"
[[steps]]
id = "deploy"
title = "Deploy"
needs = ["test-unit", "test-integration"] # Waits for both
```
## Gates
Add gates for async coordination:
```toml
[[steps]]
id = "approval"
title = "Manager approval"
type = "human"
[steps.gate]
type = "human"
approvers = ["manager"]
[[steps]]
id = "deploy"
title = "Deploy to production"
needs = ["approval"]
```
## Aspects (Cross-cutting)
Apply transformations to matching steps:
```toml
formula = "security-scan"
type = "aspect"
[[advice]]
target = "*.deploy" # Match all deploy steps
[advice.before]
id = "security-scan-{step.id}"
title = "Security scan before {step.title}"
```
## Formula Locations
Formulas are searched in order:
1. `.beads/formulas/` (project-level)
2. `~/.beads/formulas/` (user-level)
3. Built-in formulas
## Using Formulas
```bash
# List available formulas
bd mol list
# Pour formula into molecule
bd pour <formula-name> --var key=value
# Preview what would be created
bd pour <formula-name> --dry-run
```
## Creating Custom Formulas
1. Create file: `.beads/formulas/my-workflow.formula.toml`
2. Define structure (see examples above)
3. Use with: `bd pour my-workflow`
## Example: Release Formula
```toml
formula = "release"
description = "Standard release workflow"
version = 1
[vars.version]
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"
[[steps]]
id = "bump-version"
title = "Bump version to {{version}}"
[[steps]]
id = "changelog"
title = "Update CHANGELOG"
needs = ["bump-version"]
[[steps]]
id = "test"
title = "Run full test suite"
needs = ["changelog"]
[[steps]]
id = "build"
title = "Build release artifacts"
needs = ["test"]
[[steps]]
id = "tag"
title = "Create git tag v{{version}}"
needs = ["build"]
[[steps]]
id = "publish"
title = "Publish release"
needs = ["tag"]
type = "human"
```

216
website/docs/workflows/gates.md Normal file
View File

@@ -0,0 +1,216 @@
---
id: gates
title: Gates
sidebar_position: 4
---
# Gates
Gates are async coordination primitives for workflow orchestration.
## What are Gates?
Gates block step progression until a condition is met:
- Human approval
- Timer expiration
- External event (GitHub PR, CI, etc.)
## Gate Types
### Human Gate
Wait for human approval:
```toml
[[steps]]
id = "deploy-approval"
title = "Approval for production deploy"
type = "human"
[steps.gate]
type = "human"
approvers = ["team-lead", "security"]
require_all = false # Any approver can approve
```
### Timer Gate
Wait for a duration:
```toml
[[steps]]
id = "cooldown"
title = "Wait for cooldown period"
[steps.gate]
type = "timer"
duration = "24h"
```
Durations: `30m`, `2h`, `24h`, `7d`
### GitHub Gate
Wait for GitHub events:
```toml
[[steps]]
id = "wait-for-ci"
title = "Wait for CI to pass"
[steps.gate]
type = "github"
event = "check_suite"
status = "success"
```
```toml
[[steps]]
id = "wait-for-merge"
title = "Wait for PR merge"
[steps.gate]
type = "github"
event = "pull_request"
action = "closed"
merged = true
```
## Gate States
| State | Description |
|-------|-------------|
| `pending` | Waiting for condition |
| `open` | Condition met, can proceed |
| `closed` | Step completed |
## Using Gates in Workflows
### Approval Flow
```toml
formula = "production-deploy"
[[steps]]
id = "build"
title = "Build production artifacts"
[[steps]]
id = "staging"
title = "Deploy to staging"
needs = ["build"]
[[steps]]
id = "qa-approval"
title = "QA sign-off"
needs = ["staging"]
type = "human"
[steps.gate]
type = "human"
approvers = ["qa-team"]
[[steps]]
id = "production"
title = "Deploy to production"
needs = ["qa-approval"]
```
### Scheduled Release
```toml
formula = "scheduled-release"
[[steps]]
id = "prepare"
title = "Prepare release"
[[steps]]
id = "wait-window"
title = "Wait for release window"
needs = ["prepare"]
[steps.gate]
type = "timer"
duration = "2h"
[[steps]]
id = "deploy"
title = "Deploy release"
needs = ["wait-window"]
```
### CI Integration
```toml
formula = "ci-gated-deploy"
[[steps]]
id = "create-pr"
title = "Create pull request"
[[steps]]
id = "wait-ci"
title = "Wait for CI"
needs = ["create-pr"]
[steps.gate]
type = "github"
event = "check_suite"
status = "success"
[[steps]]
id = "merge"
title = "Merge PR"
needs = ["wait-ci"]
type = "human"
```
## Gate Operations
### Check Gate Status
```bash
bd show bd-xyz.3 # Shows gate state
bd show bd-xyz.3 --json | jq '.gate'
```
### Manual Gate Override
For human gates:
```bash
bd gate approve bd-xyz.3 --approver "team-lead"
```
### Skip Gate (Emergency)
```bash
bd gate skip bd-xyz.3 --reason "Emergency deploy"
```
## waits-for Dependency
The `waits-for` dependency type creates fan-in patterns:
```toml
[[steps]]
id = "test-a"
title = "Test suite A"
[[steps]]
id = "test-b"
title = "Test suite B"
[[steps]]
id = "integration"
title = "Integration tests"
waits_for = ["test-a", "test-b"] # Fan-in: waits for all
```
## Best Practices
1. **Use human gates for critical decisions** - Don't auto-approve production
2. **Add timeout to timer gates** - Prevent indefinite blocking
3. **Document gate requirements** - Make approvers clear
4. **Use CI gates for quality** - Block on test failures

94
website/docs/workflows/index.md Normal file
View File

@@ -0,0 +1,94 @@
---
id: index
title: Workflows
sidebar_position: 1
---
# Workflows
Beads provides powerful workflow primitives for complex, multi-step processes.
## Chemistry Metaphor
Beads uses a molecular chemistry metaphor:
| Phase | Storage | Synced | Use Case |
|-------|---------|--------|----------|
| **Proto** (solid) | Built-in | N/A | Reusable templates |
| **Mol** (liquid) | `.beads/` | Yes | Persistent work |
| **Wisp** (vapor) | `.beads-wisp/` | No | Ephemeral operations |
## Core Concepts
### Formulas
Declarative workflow templates in TOML or JSON:
```toml
formula = "feature-workflow"
version = 1
type = "workflow"
[[steps]]
id = "design"
title = "Design the feature"
type = "human"
[[steps]]
id = "implement"
title = "Implement the feature"
needs = ["design"]
```
### Molecules
Work graphs with parent-child relationships:
- Created by instantiating formulas with `bd pour`
- Steps have dependencies (`needs`)
- Progress tracked via issue status
### Gates
Async coordination primitives:
- **Human gates** - Wait for human approval
- **Timer gates** - Wait for duration
- **GitHub gates** - Wait for PR merge, CI, etc.
### Wisps
Ephemeral operations that don't sync to git:
- Created with `bd wisp`
- Stored in `.beads-wisp/` (gitignored)
- Auto-expire after completion
## Workflow Commands
| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol list` | List molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |
## Simple Example
```bash
# Create a release workflow
bd pour release --var version=1.0.0
# View the molecule
bd mol show release-1.0.0
# Work through steps
bd update release-1.0.0.1 --status in_progress
bd close release-1.0.0.1
# Next step becomes ready...
```
## Navigation
- [Molecules](/workflows/molecules) - Work graphs and execution
- [Formulas](/workflows/formulas) - Declarative templates
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral operations

166
website/docs/workflows/molecules.md Normal file
View File

@@ -0,0 +1,166 @@
---
id: molecules
title: Molecules
sidebar_position: 2
---
# Molecules
Molecules are work graphs created from formulas.
## What is a Molecule?
A molecule is a persistent instance of a formula:
- Contains steps with dependencies
- Tracked in `.beads/` (syncs with git)
- Steps map to issues with parent-child relationships
## Creating Molecules
### From Formula
```bash
# Pour a formula into a molecule
bd pour <formula-name> [--var key=value]
```
**Example:**
```bash
bd 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
```bash
bd mol list
bd mol list --json
```
### Viewing a Molecule
```bash
bd mol show <molecule-id>
bd dep tree <molecule-id> # Shows full hierarchy
```
## Working with Molecules
### Step Dependencies
Steps have `needs` dependencies:
```toml
[[steps]]
id = "implement"
title = "Implement feature"
needs = ["design"] # Must complete design first
```
The `bd ready` command respects these:
```bash
bd ready # Only shows steps with completed dependencies
```
### Progressing Through Steps
```bash
# Start a step
bd update bd-xyz.1 --status in_progress
# Complete a step
bd close bd-xyz.1 --reason "Done"
# Check what's ready next
bd ready
```
### Viewing Progress
```bash
# See blocked steps
bd blocked
# See molecule stats
bd stats
```
## Molecule Lifecycle
```
Formula (template)
↓ bd pour
Molecule (instance)
↓ work steps
Completed Molecule
↓ optional cleanup
Archived
```
## Advanced Features
### Bond Points
Formulas can define bond points for composition:
```toml
[compose]
[[compose.bond_points]]
id = "entry"
step = "design"
position = "before"
```
### Hooks
Execute actions on step completion:
```toml
[[steps]]
id = "build"
title = "Build project"
[steps.on_complete]
run = "make build"
```
### Pinning Work
Assign molecules to agents:
```bash
# Pin to current agent
bd pin bd-xyz --start
# Check what's pinned
bd hook
```
## Example Workflow
```bash
# 1. Create molecule from formula
bd pour feature-workflow --var name="dark-mode"
# 2. View structure
bd dep tree bd-xyz
# 3. Start first step
bd update bd-xyz.1 --status in_progress
# 4. Complete and progress
bd close bd-xyz.1
bd ready # Shows next steps
# 5. Continue until complete
```
## See Also
- [Formulas](/workflows/formulas) - Creating templates
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral workflows

129
website/docs/workflows/wisps.md Normal file
View File

@@ -0,0 +1,129 @@
---
id: wisps
title: Wisps
sidebar_position: 5
---
# Wisps
Wisps are ephemeral workflows that don't sync to git.
## What are Wisps?
Wisps are "vapor phase" molecules:
- Stored in `.beads-wisp/` (gitignored)
- Don't sync with git
- Auto-expire after completion
- Perfect for temporary operations
## Use Cases
| Scenario | Why Wisp? |
|----------|-----------|
| Local experiments | No need to pollute git history |
| CI/CD pipelines | Ephemeral by nature |
| Scratch workflows | Quick throwaway work |
| Agent coordination | Local-only coordination |
## Creating Wisps
```bash
# Create wisp from formula
bd wisp create <formula> [--var key=value]
# Example
bd wisp create quick-check --var target=auth-module
```
## Wisp Commands
```bash
# List wisps
bd wisp list
bd wisp list --json
# Show wisp details
bd wisp show <wisp-id>
# Delete wisp
bd wisp delete <wisp-id>
# Delete all completed wisps
bd wisp cleanup
```
## Wisp vs Molecule
| Aspect | Molecule | Wisp |
|--------|----------|------|
| Storage | `.beads/` | `.beads-wisp/` |
| Git sync | Yes | No |
| Persistence | Permanent | Ephemeral |
| Use case | Tracked work | Temporary ops |
## Phase Control
Use `bd mol bond` to control phase:
```bash
# Force liquid (persistent molecule)
bd mol bond <formula> <target> --pour
# Force vapor (ephemeral wisp)
bd mol bond <formula> <target> --wisp
```
## Example: Quick Check Workflow
Create a wisp for running checks:
```toml
# .beads/formulas/quick-check.formula.toml
formula = "quick-check"
description = "Quick local checks"
[[steps]]
id = "lint"
title = "Run linter"
[[steps]]
id = "test"
title = "Run tests"
needs = ["lint"]
[[steps]]
id = "build"
title = "Build project"
needs = ["test"]
```
Use as wisp:
```bash
bd wisp create quick-check
# Work through steps...
bd wisp cleanup # Remove when done
```
## Auto-Expiration
Wisps can auto-expire:
```toml
[wisp]
expires_after = "24h" # Auto-delete after 24 hours
```
Or cleanup manually:
```bash
bd wisp cleanup --all # Remove all wisps
bd wisp cleanup --completed # Remove only completed
```
## Best Practices
1. **Use wisps for local-only work** - Don't sync to git
2. **Clean up regularly** - `bd wisp cleanup`
3. **Use molecules for tracked work** - Wisps are ephemeral
4. **Consider CI/CD wisps** - Perfect for pipeline steps