beads/.github/copilot-instructions.md
matt wilkie 6e506b6ddd
Add PR preflight and contributor intake guidance (#3470)
* Handle legacy PR status contexts

* docs: add contributor PR intake checklist

* docs: wire PR preflight into agent guidance
2026-04-24 15:44:06 -07:00

138 lines
4.8 KiB
Markdown

# 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 tests` 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
- Install git hooks: `bd hooks install`
- Use `bd dolt push` / `bd dolt pull` for remote sync
- Before implementing related work, opening a PR, or merging/closing a PR, run:
`scripts/pr-preflight.sh --search "<topic>" --repo gastownhall/beads` or
`scripts/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
```bash
# 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
1. **Check ready work**: `bd ready --json`
2. **Claim task**: `bd update <id> --claim`
3. **Work on it**: Implement, test, document
4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from:<parent-id> --json`
5. **Complete**: `bd close <id> --reason "Done" --json`
6. **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 `--json` flag for programmatic use
- ✅ Use `bd dolt push` / `bd dolt pull` for 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](../AGENTS.md)**