Merge branch 'main' of https://github.com/steveyegge/beads

2025-11-23 21:29:25 -08:00
parent aa2df73f6d cb604da09c
commit 5fdbd7785a
8 changed files with 1600 additions and 685 deletions
--- a/.beads/BD_GUIDE.md
+++ b/.beads/BD_GUIDE.md
@@ -0,0 +1,291 @@
+<!-- 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
+
+This file contains canonical bd (beads) workflow instructions for AI agents.
+It is auto-generated and version-stamped to track bd upgrades.
+
+> **For project-specific instructions**, see AGENTS.md in the repository root.
+> This file only covers bd tool usage, not project-specific workflows.
+
+---
+
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Auto-syncs to JSONL for version control
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+```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
+```
+
+**Claim and update:**
+```bash
+bd update bd-42 --status in_progress --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### 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)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
+
+### Auto-Sync
+
+bd automatically syncs with git:
+- Exports to `.beads/issues.jsonl` after changes (5s debounce)
+- Imports from JSONL when newer (e.g., after `git pull`)
+- No manual export/import needed!
+
+### GitHub Copilot Integration
+
+If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading.
+Run `bd onboard` to get the content, or see step 2 of the onboard instructions.
+
+### MCP Server (Recommended)
+
+If using Claude or MCP-compatible clients, install the beads MCP server:
+
+```bash
+pip install beads-mcp
+```
+
+Add to MCP config (e.g., `~/.config/claude/config.json`):
+```json
+{
+  "beads": {
+    "command": "beads-mcp",
+    "args": []
+  }
+}
+```
+
+Then use `mcp__beads__*` functions instead of CLI commands.
+
+### Managing AI-Generated Planning Documents
+
+AI assistants often create planning and design documents during development:
+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
+
+**Best Practice: Use a dedicated directory for these ephemeral files**
+
+**Recommended approach:**
+- Create a `history/` directory in the project root
+- Store ALL AI-generated planning/design docs in `history/`
+- Keep the repository root clean and focused on permanent project files
+- Only access `history/` when explicitly asked to review past planning
+
+**Example .gitignore entry (optional):**
+```
+# AI planning documents (ephemeral)
+history/
+```
+
+**Benefits:**
+- ✅ Clean repository root
+- ✅ Clear separation between ephemeral and permanent documentation
+- ✅ Easy to exclude from version control if desired
+- ✅ Preserves planning history for archeological research
+- ✅ Reduces noise when browsing the project
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ✅ Store AI planning docs in `history/` directory
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+- ❌ Do NOT clutter repo root with planning documents
+
+For more details, see README.md and QUICKSTART.md.
+
+---
+
+# GitHub Copilot Instructions for Beads
+
+## Project Overview
+
+**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
+- Auto-sync with Git via JSONL
+- AI-optimized CLI with JSON output
+- 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.
+
+### Essential Commands
+
+```bash
+# Find work
+bd ready --json                    # Unblocked issues
+bd stale --days 30 --json          # Forgotten issues
+
+# Create and manage
+bd create "Title" -t bug|feature|task -p 0-4 --json
+bd update <id> --status in_progress --json
+bd close <id> --reason "Done" --json
+
+# Search
+bd list --status open --priority 1 --json
+bd show <id> --json
+
+# Sync (CRITICAL at end of session!)
+bd sync  # Force immediate export/commit/push
+```
+
+### Workflow
+
+1. **Check ready work**: `bd ready --json`
+2. **Claim task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json`
+5. **Complete**: `bd close <id> --reason "Done" --json`
+6. **Sync**: `bd sync` (flushes changes to git immediately)
+
+### 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
+│       └── 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)
+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
+- ✅ Run `bd sync` at end of sessions
+- ✅ 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)
+
+---
+
+**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
+bd onboard --output .beads/BD_GUIDE.md
+```
--- a/.beads/beads.jsonl
+++ b/.beads/beads.jsonl