Beads Workflow

This project uses Beads for AI-native issue tracking and persistent memory.

What is Beads?

Beads (bd) is a git-backed issue tracker designed for AI-supervised coding workflows. It provides:

• Persistent memory — Cross-session context (solves "Memento problem")
• Dependency-aware graph — bd ready shows only unblocked work
• Hash-based IDs — No collisions when multiple agents work concurrently
• Git-backed storage — .beads/issues.jsonl is version-controlled

Installation

# macOS/Linux (recommended)
brew install beads

# Or universal install script
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Verify: bd version

Initialize in Project

cd /path/to/villaPayment3
bd init --quiet

Creates .beads/ directory with issues.jsonl (git-tracked) and beads.db (gitignored).

Essential Commands for AI Agents

Command	Purpose
bd prime	Inject workflow context (~1-2k tokens) at session start
bd ready --json	Find unblocked work
bd create "Title" --description "..." -t task -p 1 --json	Create issue
bd update bd-xxx --status in_progress --json	Start work
bd close bd-xxx --reason "..." --json	Complete work
bd sync	Persist changes to git — ALWAYS run before session end

Best Practices

• Always use --json for programmatic access
• Always include --description when creating issues
• Track discovered issues with bd create "..." --deps discovered-from:bd-xxx --json

GitHub Sync

When .beads/issues.jsonl is pushed, a GitHub Action syncs new Beads issues to GitHub Issues (create-only, no mapping file). Beads issues are created as GitHub Issues with a Beads ID: bd-xxx marker in the body for deduplication.

Documentation

• Beads Official Docs