Github Lanes Bridge

---
name: github-lanes-bridge
description: Use when bridging GitHub and Lanes — importing GitHub issues into Lanes for local Claude Code execution, batch-spawning sessions per ticket, decomposing one GitHub issue into multiple Lanes sub-issues with dependencies, or posting session results (PR links, comments, follow-up issues) back to GitHub. Triggers on phrases like "import from GitHub", "bring this GitHub issue into Lanes", "comment back on the PR/issue", "spin off a GitHub issue from this Lanes ticket", or any mention of both GitHub and Lanes in the same request. Uses the Lanes MCP's built-in lanes_github_* tools — no separate GitHub MCP needed (the user must have connected GitHub in Lanes settings).
---

# GitHub ↔ Lanes bridge

Use this skill to move work between GitHub (where issues and PRs live) and Lanes (the local agent execution board). Typical flows: pull an issue into Lanes, run a session on it, then push the outcome (a PR-linking comment, or a new follow-up issue) back to GitHub.

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_github_*`) never address sessions directly.

`lanes_start_session` always **adds** a session, and its launch is asynchronous. In the batch flows below, call it exactly once per issue and record the slot it returns. Never re-call it because a session looks missing — an empty status read inside the launch window is expected. See "Starting is asynchronous" in `lanes-sessions`.

## When to use

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

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

## Prerequisites

- **Lanes MCP must be connected** — verify with `lanes_list_components`. If missing, run `/lanes-desktop:setup-mcp`.
- **GitHub must be connected inside Lanes** — verify with `lanes_github_list_repos`. If it returns a "not connected" error, ask the user to connect GitHub from **Lanes → Settings → GitHub** (OAuth flow). The token is read from `integrations.json` on every call. GitHub tokens don't expire, so no refresh logic to worry about.

There is no standalone GitHub MCP required. The same Lanes MCP that exposes `lanes_list_issues` also exposes `lanes_github_list_repos`, `lanes_github_get_issue`, etc. — they're additional tools on the same server.

## The GitHub tool surface

| Tool | Purpose |
|---|---|
| `lanes_github_list_repos` | List repos the user can access (owner, collaborator, or org member). Sorted by most-recently-pushed. Each is `{ id: "owner/name", name: "owner/name" }`. |
| `lanes_github_list_issues` | First 50 open issues in a repo, most-recently-updated first. PRs are filtered out automatically. |
| `lanes_github_search_issues` | Free-text search via the `/search/issues` endpoint. When the query is a pure number (`"#9"`, `"9"`), the exact-match issue is prepended. |
| `lanes_github_get_issue` | Single issue by **number** (passed as a string, e.g. `"42"`). |
| `lanes_github_create_issue` | Open a new issue. Labels are GitHub label **names** (not IDs). |
| `lanes_github_comment_on_issue` | Post a comment on an issue or PR. (GitHub uses the same endpoint for both.) |

Returned `ExternalIssue` shape:

```json
{
  "provider": "github",
  "externalId": "42",          // issue number as a string
  "externalKey": "#42",
  "externalUrl": "https://github.com/owner/name/issues/42",
  "title": "...",
  "description": "...",
  "state": "open",
  "updatedAt": 1715600000000
}
```

## Field mapping (GitHub → Lanes)

| GitHub | Lanes | Notes |
|---|---|---|
| `externalKey` (e.g. `#42`) | Title prefix + description marker | Used as the dedup key. |
| `title` | `title` | Pass through. |
| `body` (markdown) | `description` | Prepend a marker line: `GitHub: owner/name#42 — <externalUrl>` so round-tripping is trivial. |
| `state` (`open` / `closed`) | `step` | `open` → `backlog`/`planning` (your call); `closed` → `done` if explicitly importing closed issues. |
| upstream `externalId` (issue number) | `externalId` on `lanes_create_issue` | Pass through. |
| upstream `externalUrl` | `externalUrl` on `lanes_create_issue` | Pass through. |
| upstream `externalKey` | `externalKey` on `lanes_create_issue` | Pass through. |
| `labels` | `tags` | Different ID spaces. Look up Lanes label UUIDs via `lanes_list_labels` and map by name. Missing Lanes labels: ask user before creating. |

`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 GitHub issue → one Lanes session)

```
1. lanes_github_list_repos                                // (or user supplies "owner/name")
2. lanes_github_search_issues { repo: "owner/name", query: "#42" }
   or lanes_github_get_issue { repo, number: "42" }
3. lanes_list_issues { search: "owner/name#42" }          // dedup check
4. lanes_list_components                                  // pick componentId
5. lanes_create_issue {
     title: "owner/name#42 · <github title>",
     description: "GitHub: owner/name#42 — <externalUrl>\n\n<github body>",
     componentId,
     cwd,
     worktreeStrategy: "create",
     worktreeName: "gh/owner-name-42",
     externalProvider: "github",
     externalId: "42",
     externalKey: "#42",
     externalUrl: "<github url>",
     externalSyncedAt: <now epoch ms>
   }
6. lanes_start_session { issueId, planMode: true }
```

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

### B. Backlog import (filter GitHub → bulk Lanes issues)

```
1. lanes_github_list_issues { repo }   (capped at 50)
   or lanes_github_search_issues { repo, query: "label:p0" }
   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 GitHub issue:
     - dedup via lanes_list_issues { search: "<externalKey>" }
     - lanes_create_issue (with marker, mapped labels → tags, external* metadata)
5. (Optional) batch lanes_start_session in plan mode with
   flags: [{ flag: "dangerously-skip-permissions", value: "", kind: "flag" }]
```

For wider sweeps, prefer `lanes_github_search_issues` with explicit qualifiers (`label:foo`, `assignee:@me`, `milestone:"v2"`) over `list_issues` with no filter — GitHub's search syntax composes naturally inside the query string.

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

```
1. lanes_github_get_issue { repo, number }                // 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 GitHub 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.
```

If the team needs sub-issues visible upstream too, call `lanes_github_create_issue` for each and add their `#N` 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_github_comment_on_issue {
     repo: "owner/name",
     number: "42",
     body: "Implemented locally via Lanes #<lanesId>. PR: <PR URL>\n\n<stat summary>"
   }
4. (Optional) lanes_github_create_issue for follow-up work surfaced during the
   session.
5. lanes_move_issue { id: lanesId, step: "done" }
```

PRs and issues share the comment endpoint on GitHub — you can use `lanes_github_comment_on_issue` to comment on a PR by passing its number.

## Idempotency

Always include `GitHub: owner/name#N` in the Lanes description (and ideally in the title prefix). Before importing, run `lanes_list_issues { search: "owner/name#N" }` and skip if a match is found. For backlog imports, do the dedup check per-issue, not just up-front, so partially-imported batches can resume cleanly.

## Common pitfalls

- ❌ **Passing the GitHub issue number as a JSON integer.** The tool expects a string (e.g. `"42"`, not `42`) so the same parameter shape works for arbitrary external-id forms.
- ❌ **Forgetting `external*` metadata on import.** Without them, the Lanes UI can't show the "open in GitHub" badge or refresh the description.
- ❌ **Using `lanes_github_list_issues` and expecting PRs.** The endpoint mixes issues and PRs, but the tool filters PRs out (matching the renderer). Use the GitHub UI or `gh pr list` for PRs — there's no `lanes_github_list_prs` tool today.
- ❌ **Passing GitHub label IDs to `lanes_github_create_issue`.** Labels are by **name** (string), not ID — GitHub's REST API expects names.
- ❌ **Skipping the dedup marker.** Without `GitHub: owner/name#N` in the description, a re-run double-imports the same ticket.
- ❌ **Auto-pushing branches or opening PRs without user consent.** Never do remote git operations 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 GitHub comments mid-run.
- ❌ **Assuming `lanes_github_*` are read-only.** `lanes_github_create_issue` and `lanes_github_comment_on_issue` write to upstream — always confirm with the user before invoking on production repos.