beads-linear-sync

Files (2)

• SKILL.md
• sync.sh · scripts/

SKILL.md (first lines)

# /beads-linear-sync

Bidirectional sync between `br` (beads_rust) and `linear` CLI. Beads is the agent workspace; Linear is the human UI.

## Architecture

```
Linear (human UI)  <──pull──>  beads (agent workspace)
                   <──push──>
```

- **Pull**: Import Linear issues into beads so agents can work locally
- **Push**: Update Linear to reflect beads state changes (status, priority, new issues)
- **Reconcile**: Detect drift, report conflicts, resolve with configurable policy

## Prerequisites

```bash
br --version    # beads_rust CLI
linear --version  # Linear CLI (schpet/linear-cli)
```

Both must be authenticated. Beads must be initialized (`br init` if no `.beads/` dir).

## Arguments

| Flag | Default | Description |
|------|---------|-------------|
| `--mode` | `pull` | `pull`, `push`, `reconcile`, or `dry-run` |
| `--project` | none | Linear project filter |
| `--team` | none | Linear team key filter |
| `--cycle` | none | Linear cycle filter (e.g., `active`) |
| `--conflict` | `newest` | Conflict policy: `newest`, `prefer-local`, `prefer-linear` |
| `--label` | none | Apply a Linear label to agent-created issues (e.g., `agent-managed`) |

## State Mapping

| Linear State | Beads Status | Direction | Notes |
|---|---|---|---|
| `triage` | `open` | pull only | push: `open` -> `unstarted` (lossy; triage/backlog collapse) |
| `backlog` | `open` | pull only | push: `open` -> `unstarted` (lossy; triage/backlog collapse) |
| `unstarted` | `open` | both | |
| `started` | `in_progress` | both | |
| `completed` | `closed` | both | |
| `canceled` | `closed` | pull only | push: `closed` -> `completed` (lossy; canceled state lost) |

**Lossy mappings**: Beads has 3 statuses vs Linear's 6 states. Pulling is lossless, but pushing `open` always becomes `unstarted` and `closed` always becomes `completed`. If the original Linear state was `triage`, `backlog`, or `canceled`, that nuance is lost on push. To preserve it, store the original Linear state in the `--external-ref` or description marker.

| Linear Priority | Beads Priority | Notes |
|---|---|---|
| 0 (No priority) | P4 | backlog |
| 1 (Urgent) | P0 | critical |
| 2 (High) | P1 | high |
| 3 (Medium) | P2 | medium |
| 4 (Low) | P3 | low |

## Workflow

### 1. Detect Context

```bash
# Verify tools available
br --version 2>/dev/null || { echo "br not found"; exit 1; }
linear --version 2>/dev/null || { echo "linear not found"; exit 1; }

# Check beads initialized
br info 2>/dev/null || { echo "No .beads/ dir; run br init first"; exit 1; }

# Get Linear team context
linear team list --no-pager 2>/dev/null | head -5
```

### 2. Pull (Linear -> Beads)

Import Linear issues into beads. Safe by default; never overwrites local beads changes without confirmation.

```bash
# 1. Fetch Linear issues (scoped). linear list has no --json; parse text output
#    Or fetch each issue individually with --json for structured data
linear issue list --all-states --all-assignees --limit 100 --no-pager
# For structured data, iterate identifiers through:
linear issue view ENG-123 --json --no-pager

# 2. For each Linear issue, check if bead exists
#    Match by: Linear URL in bead description, or title match
br search "ENG-123" 2>/dev/null

# 3. Create missing beads (use --external-ref for the Linear link)
br create --title "Issue title" --priority 2 --status open \
  --external-ref "linear:ENG-123" \
  --description "Linear: ENG-123 - https://linear.app/team/issue/ENG-123"

# 4. Update existing beads if Linear state is newer
br update <bead-id> --status in_progress --priority 1
```

**Matching strategy** (in priority order):
1. External ref match: `br list --json | jq '.[] | select(.external_ref == "linear:ENG-123")'`
2. Description contains Linear identifier: `br list --desc-contains "ENG-123"`
3. Title search: `br search "issue title keywords"`

Note: `br search` is free-text (title-oriented). `--external-ref` is not directly queryable; use `br list --json` + filter for structured matching.

### 3. Push (Beads -> Linear)

Update Linear to reflect beads state. Only pushes changes since last sync.

```bash
# 1. List beads with recent changes
br list --status open --json 2>/dev/null
br list --status closed --json 2>/dev/null
br list --status in_progress --json 2>/dev/null

# 2. For each bead with a Linear link, check if states match
linear issue view ENG-123 --json --no-pager

# 3. Update Linear if bead state is newer
linear issue update ENG-123 --state started
linear issue update ENG-123 --priority 2

From thunter009/skills, MIT.

More from thunter009/skills