beads/examples
Steve Yegge 1cc238f61d feat: Add agent upgrade awareness documentation and tooling
Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.

## Changes

### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239

### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
  - Auto-detects bd version changes via .beads/metadata.json
  - Shows bd info --whats-new when upgrade detected
  - Auto-updates outdated git hooks
  - Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
  - Claude Code, GitHub Copilot, Cursor integration patterns
  - Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section

## Impact

Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features

Works today with zero bd code changes required!

Related: #239

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 16:29:56 -08:00
..
bash-agent Add Agent Mail documentation and bash-agent integration 2025-11-08 01:10:20 -08:00
bd-example-extension-go Fix SQLite driver name mismatch causing "unknown driver" errors (#252) 2025-11-07 14:19:14 -08:00
claude-code-skill Fix #264 and #262: Remove stale --resolve-collisions references 2025-11-08 13:18:50 -08:00
claude-desktop-mcp feat(mcp): Setup beads-mcp for PyPI distribution 2025-10-14 18:07:22 -07:00
compaction Add comprehensive compaction documentation 2025-10-16 01:09:48 -07:00
contributor-workflow feat: Add bd init --contributor and --team wizards 2025-11-05 19:04:14 -08:00
git-hooks Add tests and documentation for --shared hooks feature 2025-11-23 12:39:11 -08:00
github-import Remove collision-era language from docs and code 2025-10-31 14:24:50 -07:00
go-agent Add go.mod to go-agent example to fix goreleaser 2025-11-08 23:10:53 -08:00
library-usage Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
markdown-to-jsonl feat: Add markdown-to-jsonl converter example [addresses #9] 2025-10-14 13:24:20 -07:00
monitor-webui fix: use nullish coalescing to fix priority 0 bug display 2025-11-23 14:58:58 -08:00
multi-phase-development Add workflow examples: multi-phase development and multiple personas (bd-p68x) 2025-11-05 19:12:58 -08:00
multiple-personas Add workflow examples: multi-phase development and multiple personas (bd-p68x) 2025-11-05 19:12:58 -08:00
protected-branch Add comprehensive protected branch workflow documentation (bd-5ce8) 2025-11-02 18:41:51 -08:00
python-agent Complete Agent Mail documentation (bd-nl8z) 2025-11-08 02:36:27 -08:00
startup-hooks feat: Add agent upgrade awareness documentation and tooling 2025-11-23 16:29:56 -08:00
team-workflow Refactor AGENTS.md: Extract detailed instructions to prevent context pollution 2025-11-20 22:04:17 -05:00
README.md feat: Add agent upgrade awareness documentation and tooling 2025-11-23 16:29:56 -08:00

Beads Examples

This directory contains examples of how to integrate bd with AI agents and workflows.

Examples

Agent Integration

Tools & Utilities

Workflow Patterns

Quick Start

# Try the Python agent example
cd python-agent
python agent.py

# Try the bash agent example
cd bash-agent
./agent.sh

# Install git hooks
cd git-hooks
./install.sh

# REMOVED (bd-4c74): branch-merge demo - hash IDs eliminate collision resolution

Creating Your Own Agent

The basic agent workflow:

  1. Find ready work: bd ready --json --limit 1
  2. Claim the task: bd update <id> --status in_progress --json
  3. Do the work: Execute the task
  4. Discover new issues: bd create "Found bug" --json
  5. Link discoveries: bd dep add <new-id> <parent-id> --type discovered-from
  6. Complete the task: bd close <id> --reason "Done" --json

All commands support --json for easy parsing.