4.8 KiB
4.8 KiB
GitHub Copilot Instructions for Beads
Project Overview
beads (command: bd) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking.
Key Features:
- Dependency-aware issue tracking
- Auto-sync via Dolt-native replication
- AI-optimized CLI with JSON output
- Dolt server mode for background operations
- MCP server integration for Claude and other AI assistants
Tech Stack
- Language: Go 1.21+
- Storage: Dolt (version-controlled SQL database)
- 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
t.TempDir() in Go teststo avoid polluting production database - Run
go test -short ./...before committing - Never create test issues in production DB (use temporary DB)
Code Style
- Run
make ci-pr-lintbefore committing changes to Go or lint-controlled files - Follow existing patterns in
cmd/bd/for new commands - Add
--jsonflag to all commands for programmatic use - Update docs when changing behavior
Git Workflow
- Install git hooks:
bd hooks install - Use
bd dolt push/bd dolt pullfor remote sync - Before implementing related work, opening a PR, or merging/closing a PR, run:
scripts/pr-preflight.sh --search "<topic>" --repo gastownhall/beadsorscripts/pr-preflight.sh <pr-number> --repo gastownhall/beads - External contributor PRs have priority: build on them when possible, preserve tests and attribution, and never close or replace them silently.
Issue Tracking with bd
CRITICAL: This project uses bd for ALL task tracking. Do NOT create markdown TODO lists.
Essential Commands
# Find work
bd ready --json # Unblocked issues
bd stale --days 30 --json # Forgotten issues
# Create and manage (ALWAYS include --description)
bd create "Title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd update <id> --claim --json
bd close <id> --reason "Done" --json
# Search
bd list --status open --priority 1 --json
bd show <id> --json
# Sync (if remote configured)
bd dolt push # Push to Dolt remote
bd dolt pull # Pull from Dolt remote
Workflow
- Check ready work:
bd ready --json - Claim task:
bd update <id> --claim - Work on it: Implement, test, document
- Discover new work?
bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from:<parent-id> --json - Complete:
bd close <id> --reason "Done" --json - Sync:
bd dolt push(push to Dolt remote if configured)
IMPORTANT: Always include --description when creating issues. Issues without descriptions lack context for future work.
Priorities
0- Critical (security, data loss, broken builds)1- High (major features, important bugs)2- Medium (default, nice-to-have)3- Low (polish, optimization)4- Backlog (future ideas)
Project Structure
beads/
├── cmd/bd/ # CLI commands (add new commands here)
├── internal/
│ ├── types/ # Core data types
│ └── storage/ # Storage layer
│ └── dolt/ # Dolt implementation
├── integrations/
│ └── beads-mcp/ # MCP server (Python)
├── examples/ # Integration examples
├── docs/ # Documentation
└── .beads/
└── dolt/ # Dolt database (source of truth)
Available Resources
MCP Server (Recommended)
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
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
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
--jsonflag for programmatic use - ✅ Use
bd dolt push/bd dolt pullfor remote sync - ✅ Test with
t.TempDir() in Go tests - ❌ Do NOT create markdown TODO lists
- ❌ Do NOT create test issues in production DB
- ❌ Do NOT manually modify
.beads/dolt/
For detailed workflows and advanced features, see AGENTS.md