docs: document bd setup command
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
2
.beads/.gitignore
vendored
2
.beads/.gitignore
vendored
@@ -30,3 +30,5 @@ beads.right.meta.json
|
||||
!issues.jsonl
|
||||
!metadata.json
|
||||
!config.json
|
||||
deletions.jsonl
|
||||
deletions.jsonl.migrated
|
||||
|
||||
@@ -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
|
||||
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user