Prepare for public launch: comprehensive examples, docs, and tooling
This commit adds everything needed for a successful public launch: **New Documentation** - SECURITY.md: Security policy and best practices - CLAUDE.md: Complete agent instructions for contributing to beads - Enhanced README with pain points, FAQ, troubleshooting sections - Added Taskwarrior to comparison table with detailed explanation **Installation** - install.sh: One-liner installation script with platform detection - Auto-detects OS/arch, tries go install, falls back to building from source - Updated README with prominent installation instructions **Examples** (2,268+ lines of working code) - examples/python-agent/: Full Python implementation of agent workflow - examples/bash-agent/: Shell script agent with colorized output - examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer - examples/claude-desktop-mcp/: Documentation for future MCP server integration - examples/README.md: Overview of all examples **Dogfooding** - Initialized bd in beads project itself (.beads/beads.db) - Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone) - Exported to .beads/issues.jsonl for git versioning **Visual Assets** - Added screenshot showing agent using beads to README intro - Placed in .github/images/ following GitHub conventions This addresses all launch readiness items: ✅ Security policy ✅ Working agent examples (Python, Bash) ✅ Git hooks for automation ✅ FAQ addressing skeptics ✅ Troubleshooting common issues ✅ Easy installation ✅ Dogfooding our own tool ✅ Pain points that create urgency Ready to ship! 🚀 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
124
examples/bash-agent/README.md
Normal file
124
examples/bash-agent/README.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Bash Agent Example
|
||||
|
||||
A bash script demonstrating how an AI agent can use bd to manage tasks autonomously.
|
||||
|
||||
## Features
|
||||
|
||||
- Pure bash implementation (no Python/Node required)
|
||||
- Colorized terminal output
|
||||
- Automatic work discovery
|
||||
- Random issue creation to simulate real agent behavior
|
||||
- Dependency linking with `discovered-from`
|
||||
- Statistics display
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- bash 4.0+
|
||||
- bd installed: `go install github.com/steveyegge/beads/cmd/bd@latest`
|
||||
- jq for JSON parsing: `brew install jq` (macOS) or `apt install jq` (Linux)
|
||||
- A beads database initialized: `bd init`
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Make executable
|
||||
chmod +x agent.sh
|
||||
|
||||
# Run with default 10 iterations
|
||||
./agent.sh
|
||||
|
||||
# Run with custom iteration limit
|
||||
./agent.sh 20
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
The agent runs in a loop:
|
||||
|
||||
1. Looks for ready work (no blockers)
|
||||
2. Claims the task (sets status to `in_progress`)
|
||||
3. "Works" on it (simulates 1 second of work)
|
||||
4. 50% chance to discover a follow-up issue
|
||||
5. If discovered, creates and links the new issue
|
||||
6. Completes the original task
|
||||
7. Shows statistics and repeats
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
🚀 Beads Agent starting...
|
||||
Max iterations: 10
|
||||
|
||||
═══════════════════════════════════════════════════
|
||||
Beads Statistics
|
||||
═══════════════════════════════════════════════════
|
||||
Open: 5 In Progress: 0 Closed: 2
|
||||
|
||||
═══════════════════════════════════════════════════
|
||||
Iteration 1/10
|
||||
═══════════════════════════════════════════════════
|
||||
ℹ Looking for ready work...
|
||||
ℹ Claiming task: bd-3
|
||||
✓ Task claimed
|
||||
ℹ Working on: Fix authentication bug (bd-3)
|
||||
Priority: 1
|
||||
⚠ Discovered issue while working!
|
||||
✓ Created issue: bd-8
|
||||
✓ Linked bd-8 ← discovered-from ← bd-3
|
||||
ℹ Completing task: bd-3
|
||||
✓ Task completed: bd-3
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Continuous Integration**
|
||||
```bash
|
||||
# Run agent in CI to process testing tasks
|
||||
./agent.sh 5
|
||||
```
|
||||
|
||||
**Cron Jobs**
|
||||
```bash
|
||||
# Run agent every hour
|
||||
0 * * * * cd /path/to/project && /path/to/agent.sh 3
|
||||
```
|
||||
|
||||
**One-off Task Processing**
|
||||
```bash
|
||||
# Process exactly one task and exit
|
||||
./agent.sh 1
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
Edit the script to customize behavior:
|
||||
|
||||
```bash
|
||||
# Change discovery probability (line ~80)
|
||||
if [[ $((RANDOM % 2)) -eq 0 ]]; then # 50% chance
|
||||
# Change to:
|
||||
if [[ $((RANDOM % 10)) -lt 3 ]]; then # 30% chance
|
||||
|
||||
# Add assignee filtering
|
||||
bd ready --json --assignee "bot" --limit 1
|
||||
|
||||
# Add priority filtering
|
||||
bd ready --json --priority 1 --limit 1
|
||||
|
||||
# Add custom labels
|
||||
bd create "New task" -l "automated,agent-discovered"
|
||||
```
|
||||
|
||||
## Integration with Real Agents
|
||||
|
||||
This script is a starting point. To integrate with a real LLM:
|
||||
|
||||
1. Replace `do_work()` with calls to your LLM API
|
||||
2. Parse the LLM's response for tasks to create
|
||||
3. Use issue IDs to maintain context
|
||||
4. Track conversation state in issue metadata
|
||||
|
||||
## See Also
|
||||
|
||||
- [../python-agent/](../python-agent/) - Python version with more flexibility
|
||||
- [../git-hooks/](../git-hooks/) - Automatic export/import on git operations
|
||||
182
examples/bash-agent/agent.sh
Executable file
182
examples/bash-agent/agent.sh
Executable file
@@ -0,0 +1,182 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Simple AI agent workflow using bd (Beads issue tracker).
|
||||
#
|
||||
# This demonstrates the full lifecycle of an agent managing tasks:
|
||||
# - Find ready work
|
||||
# - Claim and execute
|
||||
# - Discover new issues
|
||||
# - Link discoveries
|
||||
# - Complete and move on
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
log_info() {
|
||||
echo -e "${BLUE}ℹ ${NC}$1"
|
||||
}
|
||||
|
||||
log_success() {
|
||||
echo -e "${GREEN}✓${NC} $1"
|
||||
}
|
||||
|
||||
log_warning() {
|
||||
echo -e "${YELLOW}⚠${NC} $1"
|
||||
}
|
||||
|
||||
log_error() {
|
||||
echo -e "${RED}✗${NC} $1"
|
||||
}
|
||||
|
||||
# Check if bd is installed
|
||||
if ! command -v bd &> /dev/null; then
|
||||
log_error "bd is not installed"
|
||||
echo "Install with: go install github.com/steveyegge/beads/cmd/bd@latest"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if we're in a beads-initialized directory
|
||||
if ! bd list &> /dev/null; then
|
||||
log_error "Not in a beads-initialized directory"
|
||||
echo "Run: bd init"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Find ready work
|
||||
find_ready_work() {
|
||||
bd ready --json --limit 1 2>/dev/null | jq -r '.[0] // empty'
|
||||
}
|
||||
|
||||
# Extract field from JSON
|
||||
get_field() {
|
||||
local json="$1"
|
||||
local field="$2"
|
||||
echo "$json" | jq -r ".$field"
|
||||
}
|
||||
|
||||
# Claim a task
|
||||
claim_task() {
|
||||
local issue_id="$1"
|
||||
log_info "Claiming task: $issue_id"
|
||||
bd update "$issue_id" --status in_progress --json > /dev/null
|
||||
log_success "Task claimed"
|
||||
}
|
||||
|
||||
# Simulate doing work (in real agent, this would call LLM/execute code)
|
||||
do_work() {
|
||||
local issue="$1"
|
||||
local issue_id=$(get_field "$issue" "id")
|
||||
local title=$(get_field "$issue" "title")
|
||||
local priority=$(get_field "$issue" "priority")
|
||||
|
||||
echo ""
|
||||
log_info "Working on: $title ($issue_id)"
|
||||
echo " Priority: $priority"
|
||||
|
||||
# Simulate work delay
|
||||
sleep 1
|
||||
|
||||
# Simulate discovering new work (50% chance)
|
||||
if [[ $((RANDOM % 2)) -eq 0 ]]; then
|
||||
log_warning "Discovered issue while working!"
|
||||
|
||||
# Create new issue
|
||||
local new_issue=$(bd create "Follow-up: $title" \
|
||||
-d "Discovered while working on $issue_id" \
|
||||
-p 2 \
|
||||
-t task \
|
||||
--json)
|
||||
|
||||
local new_id=$(echo "$new_issue" | jq -r '.id')
|
||||
log_success "Created issue: $new_id"
|
||||
|
||||
# Link it back to parent
|
||||
bd dep add "$new_id" "$issue_id" --type discovered-from
|
||||
log_success "Linked $new_id ← discovered-from ← $issue_id"
|
||||
|
||||
return 0 # Discovered new work
|
||||
fi
|
||||
|
||||
return 1 # No new work discovered
|
||||
}
|
||||
|
||||
# Complete a task
|
||||
complete_task() {
|
||||
local issue_id="$1"
|
||||
local reason="${2:-Completed successfully}"
|
||||
|
||||
log_info "Completing task: $issue_id"
|
||||
bd close "$issue_id" --reason "$reason" --json > /dev/null
|
||||
log_success "Task completed: $issue_id"
|
||||
}
|
||||
|
||||
# Show statistics
|
||||
show_stats() {
|
||||
echo ""
|
||||
echo "═══════════════════════════════════════════════════"
|
||||
echo " Beads Statistics"
|
||||
echo "═══════════════════════════════════════════════════"
|
||||
bd stats
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Main agent loop
|
||||
run_agent() {
|
||||
local max_iterations="${1:-10}"
|
||||
local iteration=0
|
||||
|
||||
echo ""
|
||||
echo "🚀 Beads Agent starting..."
|
||||
echo " Max iterations: $max_iterations"
|
||||
show_stats
|
||||
|
||||
while [[ $iteration -lt $max_iterations ]]; do
|
||||
iteration=$((iteration + 1))
|
||||
|
||||
echo ""
|
||||
echo "═══════════════════════════════════════════════════"
|
||||
echo " Iteration $iteration/$max_iterations"
|
||||
echo "═══════════════════════════════════════════════════"
|
||||
|
||||
# Find ready work
|
||||
log_info "Looking for ready work..."
|
||||
ready_work=$(find_ready_work)
|
||||
|
||||
if [[ -z "$ready_work" ]]; then
|
||||
log_warning "No ready work found. Agent idle."
|
||||
break
|
||||
fi
|
||||
|
||||
issue_id=$(get_field "$ready_work" "id")
|
||||
|
||||
# Claim it
|
||||
claim_task "$issue_id"
|
||||
|
||||
# Do the work
|
||||
if do_work "$ready_work"; then
|
||||
log_info "New work discovered, will process in next iteration"
|
||||
fi
|
||||
|
||||
# Complete it
|
||||
complete_task "$issue_id"
|
||||
|
||||
# Brief pause between iterations
|
||||
sleep 0.5
|
||||
done
|
||||
|
||||
echo ""
|
||||
log_success "Agent finished after $iteration iterations"
|
||||
show_stats
|
||||
}
|
||||
|
||||
# Handle Ctrl-C gracefully
|
||||
trap 'echo ""; log_warning "Agent interrupted by user"; exit 130' INT
|
||||
|
||||
# Run the agent
|
||||
run_agent "${1:-10}"
|
||||
Reference in New Issue
Block a user