diff --git a/.beads/BD_GUIDE.md b/.beads/BD_GUIDE.md index a053b9d8..a6ae83c7 100644 --- a/.beads/BD_GUIDE.md +++ b/.beads/BD_GUIDE.md @@ -1,4 +1,4 @@ - + # BD (Beads) Guide for AI Agents @@ -33,6 +33,7 @@ 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 --json # Hierarchical subtask (gets ID like epic-id.1) ``` **Claim and update:** @@ -132,6 +133,11 @@ history/ - ✅ Preserves planning history for archeological research - ✅ Reduces noise when browsing the project +### CLI Help + +Run `bd --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 @@ -139,6 +145,7 @@ history/ - ✅ 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 --help` to discover available flags - ❌ Do NOT create markdown TODO lists - ❌ Do NOT use external issue trackers - ❌ Do NOT duplicate tracking systems @@ -148,11 +155,11 @@ For more details, see README.md and QUICKSTART.md. --- -# GitHub Copilot Instructions for Beads +# GitHub Copilot Instructions -## Project Overview +## Issue Tracking with bd -**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking. +This project uses **bd (beads)** for issue tracking - a Git-backed tracker designed for AI-supervised coding workflows. **Key Features:** - Dependency-aware issue tracking @@ -161,37 +168,7 @@ For more details, see README.md and QUICKSTART.md. - Built-in daemon for background operations - MCP server integration for Claude and other AI assistants -## 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. +**CRITICAL**: Use bd for ALL task tracking. Do NOT create markdown TODO lists. ### Essential Commands @@ -202,6 +179,7 @@ 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 --json # Hierarchical subtask bd update --status in_progress --json bd close --reason "Done" --json @@ -230,60 +208,35 @@ bd sync # Force immediate export/commit/push - `3` - Low (polish, optimization) - `4` - Backlog (future ideas) -## Project Structure +### Git Workflow -``` -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 +- 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) ### MCP Server (Recommended) -Use the beads MCP server for native function calls instead of shell commands: + +For MCP-compatible clients (Claude Desktop, etc.), install the beads MCP server: - Install: `pip install beads-mcp` - Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc. -- See `integrations/beads-mcp/README.md` -### Scripts -- `./scripts/bump-version.sh --commit` - Update all version files atomically -- `./scripts/release.sh ` - Complete release workflow -- `./scripts/update-homebrew.sh ` - Update Homebrew formula +## CLI Help -### 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 +Run `bd --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 - ✅ Always use `--json` flag for programmatic use - ✅ Run `bd sync` at end of sessions -- ✅ Test with `BEADS_DB=/tmp/test.db` +- ✅ Run `bd --help` to discover available flags - ❌ Do NOT create markdown TODO lists -- ❌ Do NOT create test issues in production DB - ❌ Do NOT commit `.beads/beads.db` (JSONL only) --- -**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)** - ---- - -**Generated by bd v0.24.2** +**Generated by bd v0.29.0** To regenerate this file after upgrading bd: ```bash