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

docs: document bd setup command

Browse Source 
Add comprehensive documentation for the bd setup command which was
largely undocumented (GH#518):

- CLI_REFERENCE.md: Add new "Editor Integration" section documenting
  bd setup claude/cursor/aider commands with all flags
- INSTALLING.md: Fix incorrect reference to "bd hooks install" for
  editor integration - should be "bd setup <editor>"
- CLAUDE_INTEGRATION.md: Add Installation section with bd setup claude
  examples

Fixes: GH#518

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-16 01:08:42 -08:00
parent 56fe3f78c2
commit 39a58fd085
6 changed files with 362 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.beads/.gitignore vendored
View File

@@ -30,3 +30,5 @@ beads.right.meta.json
!issues.jsonl
!metadata.json
!config.json
deletions.jsonl
deletions.jsonl.migrated

95
.beads/BD_GUIDE.md
View File

@@ -1,4 +1,4 @@
<!-- Auto-generated by bd v0.29.0 - DO NOT EDIT MANUALLY -->
<!-- Auto-generated by bd v0.24.2 - DO NOT EDIT MANUALLY -->
<!-- Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate -->
# BD (Beads) Guide for AI Agents
@@ -33,7 +33,6 @@ bd ready --json
```bash
bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask (gets ID like epic-id.1)
```
**Claim and update:**
@@ -133,11 +132,6 @@ history/
- ✅ Preserves planning history for archeological research
- ✅ Reduces noise when browsing the project
### CLI Help
Run `bd <command> --help` to see all available flags for any command.
For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
### Important Rules
- ✅ Use bd for ALL task tracking
@@ -145,7 +139,6 @@ For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
- ✅ Link discovered work with `discovered-from` dependencies
- ✅ Check `bd ready` before asking "what should I work on?"
- ✅ Store AI planning docs in `history/` directory
- ✅ Run `bd <cmd> --help` to discover available flags
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
@@ -155,11 +148,11 @@ For more details, see README.md and QUICKSTART.md.
---
# GitHub Copilot Instructions
# GitHub Copilot Instructions for Beads
## Issue Tracking with bd
## Project Overview
This project uses **bd (beads)** for issue tracking - a Git-backed tracker designed for AI-supervised coding workflows.
**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking.
**Key Features:**
- Dependency-aware issue tracking
@@ -168,7 +161,37 @@ This project uses **bd (beads)** for issue tracking - a Git-backed tracker desig
- Built-in daemon for background operations
- MCP server integration for Claude and other AI assistants
**CRITICAL**: Use bd for ALL task tracking. Do NOT create markdown TODO lists.
## Tech Stack
- **Language**: Go 1.21+
- **Storage**: SQLite (internal/storage/sqlite/)
- **CLI Framework**: Cobra
- **Testing**: Go standard testing + table-driven tests
- **CI/CD**: GitHub Actions
- **MCP Server**: Python (integrations/beads-mcp/)
## Coding Guidelines
### Testing
- Always write tests for new features
- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database
- Run `go test -short ./...` before committing
- Never create test issues in production DB (use temporary DB)
### Code Style
- Run `golangci-lint run ./...` before committing
- Follow existing patterns in `cmd/bd/` for new commands
- Add `--json` flag to all commands for programmatic use
- Update docs when changing behavior
### Git Workflow
- Always commit `.beads/issues.jsonl` with code changes
- Run `bd sync` at end of work sessions
- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)
## Issue Tracking with bd
**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.
### Essential Commands
@@ -179,7 +202,6 @@ bd stale --days 30 --json # Forgotten issues
# Create and manage
bd create "Title" -t bug|feature|task -p 0-4 --json
bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json
@@ -208,35 +230,60 @@ bd sync # Force immediate export/commit/push
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
### Git Workflow
## Project Structure
- Always commit `.beads/issues.jsonl` with code changes
- Run `bd sync` at end of work sessions
- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)
```
beads/
├── cmd/bd/ # CLI commands (add new commands here)
├── internal/
│ ├── types/ # Core data types
│ └── storage/ # Storage layer
│ └── sqlite/ # SQLite implementation
├── integrations/
│ └── beads-mcp/ # MCP server (Python)
├── examples/ # Integration examples
├── docs/ # Documentation
└── .beads/
├── beads.db # SQLite database (DO NOT COMMIT)
└── issues.jsonl # Git-synced issue storage
```
## Available Resources
### MCP Server (Recommended)
For MCP-compatible clients (Claude Desktop, etc.), install the beads MCP server:
Use the beads MCP server for native function calls instead of shell commands:
- Install: `pip install beads-mcp`
- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.
- See `integrations/beads-mcp/README.md`
## CLI Help
### Scripts
- `./scripts/bump-version.sh <version> --commit` - Update all version files atomically
- `./scripts/release.sh <version>` - Complete release workflow
- `./scripts/update-homebrew.sh <version>` - Update Homebrew formula
Run `bd <command> --help` to see all available flags for any command.
For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
### Key Documentation
- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)
- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases
- **README.md** - User-facing documentation
- **docs/CLI_REFERENCE.md** - Complete command reference
## Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use `--json` flag for programmatic use
- ✅ Run `bd sync` at end of sessions
- ✅ Run `bd <cmd> --help` to discover available flags
- ✅ Test with `BEADS_DB=/tmp/test.db`
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT create test issues in production DB
- ❌ Do NOT commit `.beads/beads.db` (JSONL only)
---
**Generated by bd v0.29.0**
**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**
---
**Generated by bd v0.24.2**
To regenerate this file after upgrading bd:
```bash

421
.beads/issues.jsonl
View File

File diff suppressed because one or more lines are too long

23
docs/CLAUDE_INTEGRATION.md
View File

@@ -81,6 +81,29 @@ They should be:
Users who want custom Skills can create their own, but beads doesn't ship with or require them.
## Installation
```bash
# Install Claude Code hooks globally
bd setup claude
# Install for this project only
bd setup claude --project
# Use stealth mode (flush only, no git operations)
bd setup claude --stealth
# Check installation status
bd setup claude --check
# Remove hooks
bd setup claude --remove
```
**What it installs:**
- SessionStart hook: Runs `bd prime` when Claude Code starts a session
- PreCompact hook: Runs `bd prime` before context compaction to preserve workflow instructions
## Related Files
- `cmd/bd/prime.go` - Context generation

39
docs/CLI_REFERENCE.md
View File

@@ -11,6 +11,7 @@
- [Filtering & Search](#filtering--search)
- [Advanced Operations](#advanced-operations)
- [Database Management](#database-management)
- [Editor Integration](#editor-integration)
## Basic Operations
@@ -550,6 +551,44 @@ bd sync # Force immediate sync, bypass debounce
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
## Editor Integration
### Setup Commands
```bash
# Setup editor integration (choose based on your editor)
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
# Check if integration is installed
bd setup claude --check
bd setup cursor --check
bd setup aider --check
# Remove integration
bd setup claude --remove
bd setup cursor --remove
bd setup aider --remove
```
**Claude Code options:**
```bash
bd setup claude # Install globally (~/.claude/settings.json)
bd setup claude --project # Install for this project only
bd setup claude --stealth # Use stealth mode (flush only, no git operations)
```
**What each setup does:**
- **Claude Code** (`bd setup claude`): Adds hooks to Claude Code's settings.json that run `bd prime` on SessionStart and PreCompact events
- **Cursor** (`bd setup cursor`): Creates `.cursor/rules/beads.mdc` with workflow instructions
- **Aider** (`bd setup aider`): Creates `.aider.conf.yml` with bd workflow instructions
See also:
- [INSTALLING.md](INSTALLING.md#ide-and-editor-integrations) - Installation guide
- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider guide
- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Claude integration design
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide

19
docs/INSTALLING.md
View File

@@ -133,15 +133,17 @@ brew install bd
cd your-project
bd init --quiet
# 3. Install hooks for automatic context injection
bd hooks install
# 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:**
- SessionStart hook runs `bd prime` automatically
- `bd prime` injects ~1-2k tokens of workflow context
- 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 auto-sync the database
- 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
@@ -149,6 +151,13 @@ bd hooks install
- **Universal** - Works with any editor that has shell access
- **More sustainable** - Less compute per request
**Verify installation:**
```bash
bd setup claude --check # Check Claude Code integration
bd setup cursor --check # Check Cursor integration
bd setup aider --check # Check Aider integration
```
### Claude Code Plugin (Optional)
For enhanced UX with slash commands: