linear-sync

Move the Linear issues linked to the current branch through their workflow states. This skill is the single source of truth for how issues are transitioned: resolving the live state IDs, extracting issue IDs from a branch name, and the per-state transition rules. Callers decide when and whether to fire it; the mechanics live here once so the rules don't drift across the ship flow, branch cleanup, and the start-of-work transition.

Configuration

Two knobs live in

config.json

beside this file. Read it at the start of a run and use its values throughout. Edit your copied

config.json

to match the consuming repo:

Key	Meaning	Default
`linearTeamName`	Linear team name used to resolve the live state IDs. Use the name, not the key — the key is renamed over time but the name is stable.	`"ACME Skunkworks"`
`issueKeys`	Team-key prefixes that may appear in branch names. The issue-ID regex is built from these.	`["A"]`

A neutral

config.example.json

ships alongside it as a template — copy it over

config.json

and fill in your values, or edit

config.json

directly.

Usage modes

--dry-run

is passed through

$ARGUMENTS

(the agent reads it), matching the

--dry-run

"preview, change nothing" convention used across the other skills.

Normal — resolve state IDs, extract the branch's issue IDs, apply the transition, and report what moved:

bash

linear-sync

Dry run — resolve state IDs and each issue's current state, report the intended transition (or skip reason) per issue, and exit without any
save_issue
call:

bash

linear-sync --dry-run

Under

--dry-run

the resolve + read steps still run (they are read-only), so the preview is accurate; only the

save_issue

write in the transition step is skipped. End the report with

DRY RUN — no issues were changed.

Resolving the target state (do this once per run)

Call

mcp__linear-server__list_issue_statuses

with

team: <linearTeamName>

once to fetch the team's live workflow states. Each carries a stable

type

(

triage

backlog

unstarted

started

completed

canceled

), a display

name

, an

id

, and a

position

Resolve the target by
type
, not by display name. Display names are customisable — a consumer may rename

In Progress

→

Doing

In Review

→

Code Review

— so matching the literal name silently fails to find the state (the biggest correctness gap for adopters). Map each transition to a concrete state:

In Progress → the
```
started
```
state named "In Progress" (case-insensitive); else the earliest
```
started
```
by
```
position
```
.
In Review → the
```
started
```
state whose name matches "In Review" / "Review"; else, when there are ≥2
```
started
```
states, the latest
```
started
```
by
```
position
```
; else the In Progress state.
Done → the
```
completed
```
state named "Done"; else the earliest
```
completed
```
by
```
position
```
.

started

covers both In Progress and In Review, so the name match (then

position

) is what separates them; a team with a single

started

state resolves both targets to it. Use the resolved

id

in the

save_issue

call.

Pass the team name, not the key. Linear state IDs are per-team, and a workspace's team can be renamed over its lifetime (e.g. CAT → WTF → AKW → ASW), so a hardcoded key goes stale. The team name (

linearTeamName

) does not move. This is the canonical gotcha for adopters — resolve by name, every run.

Extracting issue IDs from the branch

Build the issue-ID regex deterministically — mirror the canonical, tested

buildIssueRe

in the repo-root

lib/issue-keys.mjs

, which

pnpm vendor:sync

copies into each consuming bundle (ADR-0004) and which exists for exactly this job:

Escape regex metacharacters in each key (a configured key such as
```
C++
```
would otherwise throw or silently widen the match).
Group the alternation. Wrap the keys in
```
(?:…)
```
whenever there is more than one, so the
```
-\d+
```
binds to the whole alternation:
```
\b(?:A|B)-\d+\b
```
. The naive join
```
\bA|B-\d+\b
```
is wrong — it parses as
```
\bA
```
or
```
B-\d+\b
```
, matching a bare
```
A
```
and missing
```
A-7
```
. A single key needs no wrapper:
```
\bA-\d+\b
```
.
Guard the empty case. With no configured keys, match nothing — never build an empty alternation (it would match the empty string before every
```
-<digits>
```
and inject bogus IDs like
```
-2
```
).

Match the result (with the

flag) against the upper-cased branch name — branches like

asw-7-as-acquired

carry the key in lower case, and a flow such as

--issue=A-7

produces upper-case branch names like

A-7-as-acquired

. Keeping the legacy keys means leftover branches from before a team-key rename are still recognised. Deduplicate the matches. Bogus or malformed IDs simply error on lookup and are skipped with a warning — no separate validation pass.

When a caller already has an

issues

list to hand (e.g. a changelog step emits one), use that instead of re-extracting.

Transition rules

For each issue ID, call

mcp__linear-server__get_issue

to read its current state (use its

type

, not its display name). Decide using the progression order of state types:

text

triage < backlog < unstarted < started < completed

canceled

(which also covers a

Duplicate

state) is terminal and sits outside the line. Within

started

, order by

position

, so In Progress precedes In Review. All transitions are idempotent: apply only when the current state is earlier in the progression than the resolved target; skip silently when the issue is already at or past it, or when its current type is

completed

canceled

(terminal states are never advanced automatically).

In Progress (fired when starting work on an issue) — apply from
```
triage
```
/
```
backlog
```
/
```
unstarted
```
; skip from any
```
started
```
,
```
completed
```
, or
```
canceled
```
.
In Review (fired on PR open/update inside a ship flow) — apply from
```
triage
```
/
```
backlog
```
/
```
unstarted
```
, or from a
```
started
```
state earlier by
```
position
```
than the resolved In Review (e.g. In Progress); skip once at or past In Review, or
```
completed
```
/
```
canceled
```
.
Done (fired on branch cleanup) — apply from
```
triage
```
/
```
backlog
```
/
```
unstarted
```
/
```
started
```
; skip from
```
completed
```
/
```
canceled
```
.

Apply a transition with

mcp__linear-server__save_issue

using the resolved state
id
— it is unambiguous across renames. The display-name form

state: "<target>"

works only when the consumer kept Linear's default state names.

Under
--dry-run
, skip this
save_issue
call. Still read each issue's current state with

get_issue

and decide whether it would transition, but report the intended move (e.g.

A-7: Todo → In Progress (would apply)

A-9: In Review (would skip — already at/past target)

) instead of writing it.

Canceled
is the Linear API's own US spelling — keep it as-is when referenced in code or config.

Caller responsibilities (when / whether to fire)

The skill owns the mechanics; each caller owns the policy:

Start of work — transition to
```
In Progress
```
when work begins on an issue (unless already In Progress or further along). Run automatically; no prompt.
Ship flow (PR open/update) — transition linked issues to
```
In Review
```
automatically after the PR is created or updated. No prompt.
Branch cleanup — transition orphaned issues to
```
Done
```
only after explicit confirmation, default no. Linear's GitHub integration normally handles the
```
Done
```
transition on PR merge, so this prompt exists only for the rare case where the integration didn't fire (e.g. the issue ID was added after merge).

Standalone vs inside a caller

Standalone — resolve the target state, extract the branch's issue IDs, apply the transition, and report which issues moved and which were skipped. The default target is In Progress (the start-of-work transition that has no other home).
Inside a caller — the caller supplies the target (and often the
```
issues
```
list) and decides whether to prompt; the mechanics above are unchanged.

Implementation

No supporting scripts — the skill drives the Linear MCP tools directly (

list_issue_statuses

get_issue

save_issue

). The only repo-specific inputs are the team name and the issue-ID prefixes, both read from

config.json

linear-sync

NPX Install

Tags

SKILL.md Content

linear-sync

Configuration

Usage modes

Resolving the target state (do this once per run)

Extracting issue IDs from the branch

Transition rules

Caller responsibilities (when / whether to fire)

Standalone vs inside a caller

Implementation