bd (beads) Workflow Guide

This document expands the abbreviated rules in AGENTS.md. Read this whenever you interact with task tracking, planning docs, or MCP helpers.

Why bd?

• Dependency-aware: track blockers, dependents, and discovered-from links.
• Git-friendly: bd auto-syncs to .beads/issues.jsonl, so repos capture task history.
• Agent-optimized: machine-readable JSON output (--json) plus "ready" filtering.
• Single source of truth: prevents duplicate trackers, markdown TODOs, or ad-hoc spreadsheets.

Quick Start Commands

bd ready --json -n 0                    # find unblocked work
bd create "Issue title" -t task -p 2 --json
bd update bd-42 --status in_progress --json
bd close bd-42 --reason "Completed" --json