linear-lanes-bridge

Linear ↔ Lanes bridge

Use this skill to move work between Linear (the team's source of truth) and Lanes (the local agent execution board). Typical flows: pull a ticket or a whole sprint into Lanes, run sessions on each, then push the outcome (comments, new tickets) back to Linear.

This skill assumes the lanes-sessions skill is also available — it covers the lanes_* issue/session tools in detail. This skill focuses on the bridging layer.

When a Lanes issue hosts more than one CLI session, follow the multi-session disambiguation rules in lanes-sessions (pass session on stop / resume / read_terminal). Bridge tools (lanes_linear_*) never address sessions directly.

When to use

• Work originates in Linear and you want Claude Code to do the actual implementation locally.
• You want to fan out one Linear ticket into multiple Claude sessions on sub-tasks.
• You want PR links / progress updates to flow back to Linear without leaving chat.

Don't use for ad-hoc one-off tasks that didn't start in Linear; for those, just use Lanes directly.

Prerequisites

• Lanes MCP must be connected — verify with lanes_list_components. If missing, run /lanes:setup-mcp.
• Linear must be connected inside Lanes — verify with lanes_linear_list_teams. If it returns a "not connected" error, ask the user to connect Linear from Lanes → Settings → Linear (OAuth flow). All lanes_linear_* tools read the user's token from integrations.json on every call, including a transparent refresh of expired access tokens.

There is no standalone Linear MCP required. The same Lanes MCP that exposes lanes_list_issues also exposes lanes_linear_list_teams, lanes_linear_get_issue, etc. — they're additional tools on the same server.

The Linear tool surface

Returned ExternalIssue shape:

{
  "provider": "linear",
  "externalId": "<uuid>",
  "externalKey": "ENG-123",
  "externalUrl": "https://linear.app/.../issue/ENG-123",
  "title": "...",
  "description": "...",
  "state": "In Progress",
  "updatedAt": 1715600000000
}

Field mapping (Linear → Lanes)

lanes_create_issue accepts externalProvider, externalId, externalKey, externalUrl, and externalSyncedAt — set all of them on import so the Lanes UI shows the badge and the refresh button works.

Workflow patterns

A. Single port (one Linear issue → one Lanes session)

1. lanes_linear_list_teams                                // pick teamId
2. lanes_linear_search_issues { teamId, query: "ENG-123" }
3. lanes_linear_get_issue { id: "<uuid from step 2>" }    // full description
4. lanes_list_issues { search: "ENG-123" }                // dedup check
5. lanes_list_components                                  // pick componentId
6. lanes_create_issue {
     title: "ENG-123 · <linear title>",
     description: "Linear: ENG-123 — <externalUrl>\n\n<linear description>",
     componentId,
     cwd,
     worktreeStrategy: "create",
     worktreeName: "linear/eng-123",
     externalProvider: "linear",
     externalId: "<linear uuid>",
     externalKey: "ENG-123",
     externalUrl: "<linear url>",
     externalSyncedAt: <now epoch ms>
   }
7. lanes_start_session { issueId, planMode: true }

Confirm with the user before step 7 if the ticket is non-trivial — let them review the issue first.

B. Sprint import (filter Linear → bulk Lanes issues)

1. lanes_linear_list_issues { teamId } or
   lanes_linear_search_issues { teamId, query: "<filter>" }
   Show the user the result count BEFORE importing.
2. Confirm scope with the user.
3. lanes_list_components, lanes_list_labels (cache locally)
4. For each Linear issue:
     - dedup via lanes_list_issues { search: "<externalKey>" }
     - lanes_create_issue (with marker, componentId, external* metadata)
5. (Optional) batch lanes_start_session in plan mode with
   flags: [{ flag: "dangerously-skip-permissions", value: "", kind: "flag" }]

lanes_linear_list_issues is capped at 50 — for larger sprints, narrow the query first or page via lanes_linear_search_issues with deliberate terms.

C. Decomposition (one Linear issue → many Lanes sub-issues)

1. lanes_linear_get_issue { id }                          // big ticket
2. Propose a breakdown to the user (numbered list).
3. After user approves:
     a. lanes_create_issue for the parent (the umbrella, with Linear marker).
     b. lanes_create_issue for each sub-task with
        dependencies: [parentLanesId].
4. lanes_start_session on the parent in plan mode (optional);
   start sub-tasks once their dependencies are unblocked.

The parent stays linked to Linear via the marker. Sub-tasks are Lanes-only; if the team needs them visible in Linear, call lanes_linear_create_issue for each and add their identifiers to each Lanes description.

D. Round-trip (push results back)

When a session is done and there's something concrete to report:

1. lanes_get_issue_changes { id }                  // confirm there is a diff
2. (User pushes the branch / opens a PR.)
3. lanes_linear_comment_on_issue {
     id: "<linear uuid>",
     body: "Implemented locally via Lanes #<lanesId>. PR: <URL>\n\n<stat summary>"
   }
4. (Optional) lanes_linear_create_issue for follow-up work surfaced during the
   session.
5. lanes_move_issue { id: lanesId, step: "done" }

Linear treats PR URLs in comments as first-class — they get a rich preview, so the comment is as good as a sidebar attachment for most flows.

Idempotency

Always include Linear: <EXTERNAL_KEY> in the Lanes description (and ideally in the title prefix). Before importing, run lanes_list_issues { search: "<EXTERNAL_KEY>" } and skip if a match is found. For sprint imports, do the dedup check per-issue, not just up-front, so partially-imported sprints can resume cleanly.

Common pitfalls

• ❌ Calling lanes_linear_get_issue with the identifier ("LA-9"). The tool takes the UUID. Get the UUID from list_issues / search_issues first.
• ❌ Forgetting external* metadata on import. Without them, the Lanes UI can't show the "open in Linear" badge or refresh the description.
• ❌ Bulk-importing without filters. Always narrow with lanes_linear_search_issues before fanning out.
• ❌ Skipping the dedup marker. Without Linear: <KEY> in the description, a re-run double-imports the same ticket.
• ❌ Auto-creating PRs without user consent. Never push to a remote or open a PR in Pattern D without the user explicitly asking.
• ❌ Posting back on every session start. Round-trip happens at session end (work landed). Don't spam Linear comments mid-run.
• ❌ Assuming lanes_linear_* are read-only. lanes_linear_create_issue and lanes_linear_comment_on_issue write to upstream — always confirm with the user before invoking on production data.