beads/examples
Justin Williams df5ceb5d82
feat: Linear Integration (#655)
* Add Linear integration CLI with sync and status commands

- Add `bd linear sync` for bidirectional issue sync with Linear
- Add `bd linear status` to show configuration and sync state
- Stub pull/push functions pending GraphQL client (bd-b6b.2)

* Implement Linear GraphQL client with full sync support

- Add LinearClient with auth, fetch, create, update methods
- Implement pull/push operations with Beads type mapping
- Clean up redundant comments and remove unused code

* Add configurable data mapping and dependency sync for Linear

- Add LinearMappingConfig with configurable priority/state/label/relation maps
- Import parent-child and issue relations as Beads dependencies
- Support custom workflow states via linear.state_map.* config

* Add incremental sync support for Linear integration

- Add FetchIssuesSince() method using updatedAt filter in GraphQL
- Check linear.last_sync config to enable incremental pulls
- Track sync mode (incremental vs full) in LinearPullStats

* feat(linear): implement push updates for existing Linear issues

Add FetchIssueByIdentifier method to retrieve single issues by identifier
(e.g., "TEAM-123") for timestamp comparison during push.

Update doPushToLinear to:
- Fetch Linear issue to get internal ID and UpdatedAt timestamp
- Compare timestamps: only update if local is newer
- Build update payload with title, description, priority, and state
- Call UpdateIssue for issues where local has newer changes

Closes bd-b6b.5

* Implement Linear conflict resolution strategies

- Add true conflict detection by fetching Linear timestamps via API
- Implement --prefer-linear resolution (re-import from Linear)
- Implement timestamp-based resolution (newer wins as default)
- Fix linter issues: handle resp.Body.Close() and remove unused error return

* Add Linear integration tests and documentation

- Add comprehensive unit tests for Linear mapping (priority, state, labels, relations)
- Update docs/CONFIG.md with Linear configuration reference
- Add examples/linear-workflow guide for bidirectional sync
- Remove AI section header comments from tests

* Fix Linear GraphQL filter construction and improve test coverage

- Refactor filter handling to combine team ID into main filter object
- Add test for duplicate issue relation mapping
- Add HTTP round-trip helper for testing request payload validation

* Refactor Linear queries to use shared constant and add UUID validation

- Extract linearIssuesQuery to deduplicate FetchIssues/FetchIssuesSince
- Add linearMaxPageSize constant and UUID validation with regex
- Expand test coverage for new functionality

* Refactor Linear integration into internal/linear package

- Extract types, client, and mapping logic from cmd/bd/linear.go
- Create internal/linear/ package for better code organization
- Update tests to work with new package structure

* Add linear teams command to list available teams

- Add FetchTeams GraphQL query to Linear client
- Refactor config reading to support daemon mode
- Add tests for teams listing functionality

* Refactor Linear config to use getLinearConfig helper

- Consolidate config/env var lookup using getLinearConfig function
- Add LINEAR_TEAM_ID environment variable support
- Update error messages to include env var configuration options

* Add hash ID generation and improve Linear conflict detection

- Add configurable hash ID mode for Linear imports (matches bd/Jira)
- Improve conflict detection with content hash comparison
- Enhance conflict resolution with skip/force update tracking

* Fix test for updated doPushToLinear signature

- Add missing skipUpdateIDs parameter to test call
2025-12-19 17:58:24 -08:00
..
bash-agent refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
bd-example-extension-go Update link to EXTENDING.md in example extending README 2025-12-16 16:46:25 -08:00
claude-desktop-mcp bd sync: 2025-11-26 18:07:01 2025-11-26 18:07:01 -08:00
compaction Add comprehensive compaction documentation 2025-10-16 01:09:48 -07:00
contributor-workflow docs: update beads.jsonl references to issues.jsonl 2025-12-16 01:08:46 -08:00
git-hooks Merge GH#532 2025-12-16 01:19:14 -08:00
github-import gh2jsonl: add intra-batch collision detection for hash IDs 2025-11-25 20:33:35 -08:00
jira-import fix(jira): migrate from deprecated API v2 to v3 2025-12-01 21:02:20 -08:00
library-usage test: replace manual os.Chdir with t.Chdir in tests (#457) 2025-12-04 11:21:43 -08:00
linear-workflow feat: Linear Integration (#655) 2025-12-19 17:58:24 -08:00
markdown-to-jsonl feat: Add markdown-to-jsonl converter example [addresses #9] 2025-10-14 13:24:20 -07:00
monitor-webui fix: use nullish coalescing to fix priority 0 bug display 2025-11-23 14:58:58 -08:00
multi-phase-development docs: fix bd daemon CLI syntax to use flag format (#568) 2025-12-15 21:16:02 -08:00
multiple-personas docs: fix bd daemon CLI syntax to use flag format (#568) 2025-12-15 21:16:02 -08:00
protected-branch Merge GH#409 2025-12-16 01:19:07 -08:00
python-agent refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
startup-hooks feat: Add agent upgrade awareness documentation and tooling 2025-11-23 16:29:56 -08:00
team-workflow Merge GH#409 2025-12-16 01:19:07 -08:00
README.md refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00

Beads Examples

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

Examples

Agent Integration

Tools & Utilities

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> --status in_progress --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.