beads/examples
Dmitry Verkhoturov ed915036c9
fix: backward-compatible JSONL import for all pre-v1.0 formats (#3021)
* fix: backward-compatible JSONL import for all pre-v1.0 formats

Three breaking changes accumulated across versions that prevent
importing old JSONL data:

1. Comment.ID changed from int64 to string in v1.0 — old JSONL
   with numeric comment IDs crashes the importer. Add custom
   UnmarshalJSON that accepts both types.

2. "wisp" field renamed to "ephemeral" in v0.38 — JSONL from
   v0.35–v0.37 silently loses the ephemeral flag. Map the old
   field name during import.

3. BondRef.proto_id renamed to source_id — old JSONL silently
   loses bond source references. Accept proto_id as alias.

Also improve auto-import error messaging: when upgrade recovery
fails, tell the user their data is safe and suggest bd init
--from-jsonl instead of silently swallowing the error.

* fix: use American English spelling for misspell linter

* test: add unit tests for backward-compatible UnmarshalJSON and legacy import

- TestCommentUnmarshalJSON: string IDs, numeric IDs (pre-v1.0),
  zero, large numbers, missing ID, invalid JSON
- TestBondRefUnmarshalJSON: source_id, proto_id (legacy),
  both fields (precedence), neither, invalid JSON
- TestImportFromLocalJSONL_LegacyFormats: numeric comment IDs
  survive import, wisp→ephemeral mapping (true/false/absent)
2026-04-04 22:34:12 -07:00
..

Beads Examples

This directory contains examples of how to integrate bd with AI agents and workflows.

Examples

Agent Integration

Tools & Utilities

  • monitor-webui/ - Standalone web interface for real-time issue monitoring and visualization
  • git-hooks/ - Pre-configured git hooks for automatic Dolt sync

Workflow Patterns

Quick Start

# Try the Python agent example
cd python-agent
python agent.py

# Try the bash agent example
cd bash-agent
./agent.sh

# Install git hooks
cd git-hooks
./install.sh

# REMOVED (bd-4c74): branch-merge demo - hash IDs eliminate collision resolution

Creating Your Own Agent

The basic agent workflow:

  1. Find ready work: bd ready --json --limit 1
  2. Claim the task: bd update <id> --claim --json
  3. Do the work: Execute the task
  4. Discover new issues: bd create "Found bug" --json
  5. Link discoveries: bd dep add <new-id> <parent-id> --type discovered-from
  6. Complete the task: bd close <id> --reason "Done" --json

All commands support --json for easy parsing.