beads-workflow

Beads (bd) Issue Tracking

This project uses Beads (bd) for issue tracking.

Core rules

• Track ALL work in bd (never use markdown TODOs or comment-based task lists).
• Use bd ready to find available work.
• Use bd create to track new issues/tasks/bugs.
• Use bd sync at end of session to sync with git remote.
• Git hooks auto-sync on commit/merge.

Quick reference

bd onboard                              # Get started / load workflow context
bd prime                                # Load complete workflow docs (AI-optimized)
bd ready                                # Show issues ready to work (no blockers)
bd list --status=open                   # List all open issues
bd create --title="..." --type=task     # Create new issue
bd show <id>                            # View issue details
bd update <id> --status=in_progress     # Claim work
bd close <id>                           # Mark complete
bd dep add <issue> <depends-on>         # Add dependency
bd export -o .beads/issues.jsonl        # Write the JSONL git tracks (see below)
bd sync                                 # Sync with git remote

Writes are not visible in git until you export — with -o

bd keeps issues in a local Dolt database. .beads/issues.jsonl is a passive export of it, and that file is what git tracks and what other tools read. A bd close updates the database immediately; it does not update the JSONL.

In bd 1.1.2 the export API changed: plain bd export writes to stdout. Writing the file needs -o:

bd export -o .beads/issues.jsonl     # correct
bd export                            # dumps JSONL to your terminal, changes nothing

Get this wrong and the symptom is not an error — it is bd close reporting success while git status shows nothing and the JSONL still says open. That looked exactly like bd silently losing ~50% of writes, which is how it came to be filed twice as a bug (fix-46c, fix-fyw) before the cause was found.