1cc238f61d
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>
119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
# Startup Hooks for AI Agents
|
|
|
|
This directory contains startup hook scripts that help AI agents automatically detect and adapt to changes in their environment.
|
|
|
|
## bd-version-check.sh
|
|
|
|
**Purpose:** Automatically detect bd (beads) upgrades and show what changed
|
|
|
|
**Features:**
|
|
- ✅ Detects when bd version changes between sessions
|
|
- ✅ Shows `bd info --whats-new` output automatically
|
|
- ✅ Auto-updates outdated git hooks
|
|
- ✅ Persists version tracking in `.beads/metadata.json`
|
|
- ✅ Works today - no bd code changes required!
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
# Source the script at session start (recommended)
|
|
source examples/startup-hooks/bd-version-check.sh
|
|
|
|
# Or execute it directly
|
|
bash examples/startup-hooks/bd-version-check.sh
|
|
```
|
|
|
|
### Integration Examples
|
|
|
|
#### Claude Code
|
|
|
|
If Claude Code supports startup hooks:
|
|
```bash
|
|
# Add to .claude/hooks/session-start
|
|
source examples/startup-hooks/bd-version-check.sh
|
|
```
|
|
|
|
Alternatively, manually run at the start of each coding session.
|
|
|
|
#### GitHub Copilot
|
|
|
|
Add to your shell initialization file:
|
|
```bash
|
|
# ~/.bashrc or ~/.zshrc
|
|
# Run bd version check when entering a beads project
|
|
if [ -d ".beads" ]; then
|
|
source /path/to/beads/examples/startup-hooks/bd-version-check.sh
|
|
fi
|
|
```
|
|
|
|
#### Cursor
|
|
|
|
Add to workspace settings or your shell init file following the same pattern as GitHub Copilot.
|
|
|
|
#### Generic Integration
|
|
|
|
Any AI coding environment that allows custom startup scripts can source this file.
|
|
|
|
### Requirements
|
|
|
|
- **bd (beads)**: Must be installed and in PATH
|
|
- **jq**: Required for JSON manipulation (`brew install jq` on macOS, `apt-get install jq` on Ubuntu)
|
|
- **.beads directory**: Must exist in current project
|
|
|
|
### How It Works
|
|
|
|
1. **Version Detection**: Reads current bd version and compares to `.beads/metadata.json`
|
|
2. **Change Notification**: If version changed, displays upgrade banner with what's new
|
|
3. **Hook Updates**: Checks for outdated git hooks and auto-updates them
|
|
4. **Persistence**: Updates `metadata.json` with current version for next session
|
|
|
|
### Example Output
|
|
|
|
```
|
|
🔄 bd upgraded: 0.23.0 → 0.24.2
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
🆕 What's New in bd (Current: v0.24.2)
|
|
=============================================================
|
|
|
|
## v0.24.2 (2025-11-23)
|
|
• New feature X
|
|
• Bug fix Y
|
|
• Performance improvement Z
|
|
|
|
[... rest of what's new output ...]
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
💡 Review changes above and adapt your workflow accordingly
|
|
|
|
🔧 Git hooks outdated. Updating to match bd v0.24.2...
|
|
✓ Git hooks updated successfully
|
|
```
|
|
|
|
### Edge Cases Handled
|
|
|
|
- **Not in a beads project**: Silently exits (safe to include in global shell init)
|
|
- **bd not installed**: Silently exits
|
|
- **jq not installed**: Shows warning but doesn't break
|
|
- **metadata.json missing**: Auto-creates it
|
|
- **First run**: Sets version without showing upgrade message
|
|
- **bd command fails**: Silently exits
|
|
|
|
### Troubleshooting
|
|
|
|
**Q: Script doesn't detect version change**
|
|
A: Check that `.beads/metadata.json` exists and contains `last_bd_version` field
|
|
|
|
**Q: "jq not found" warning**
|
|
A: Install jq: `brew install jq` (macOS) or `apt-get install jq` (Ubuntu)
|
|
|
|
**Q: Git hooks not auto-updating**
|
|
A: Ensure you have write permissions to `.git/hooks/` directory
|
|
|
|
### Related
|
|
|
|
- **GitHub Discussion #239**: "Upgrading beads: how to let the Agent know"
|
|
- **Parent Epic**: bd-nxgk - Agent upgrade awareness system
|
|
- **AGENTS.md**: See "After Upgrading bd" section for manual workflow
|