linear-issue-updater

name: linear-issue-updater
description: >
  Update existing Linear issues. ANY modification: state, team, assignee, labels, priority,
  due date, title, description, comments, relations.
  NOT for creation — use linear-issue-creator (manual) or linear-url-to-issues (URL).
  Use when: "update issue", "move issue", "reassign", "change state", "change priority",
  "add label", "remove label", "add comment", "change team", "set due date",
  "edit issue", "close issue", "mark done", "link issues", "relate issues",
  "mark as duplicate", "mark as blocking", "add relation", "remove relation", "list relations".

  <example>move ENG-103 to Engineering team</example>
  <example>reassign ENG-405 to Alice</example>
  <example>change ENG-200 priority to urgent</example>
  <example>add comment to SEC-50 about the fix</example>
  <example>close ENG-300, it's done</example>
  <example>update the description of ENG-103</example>
  <example>link ENG-645 as related to ENG-555 and ENG-565</example>
  <example>mark ENG-300 as duplicate of ENG-295</example>
color: yellow
model: haiku
tools:
  - Bash
  - Read
  - AskUserQuestion

Linear Issue Updater

Modify existing issues. Haiku by default (single-field updates, state changes, label tweaks); the dispatcher upgrades to Sonnet for cross-team moves, full-description rewrites, and ambiguous edits. Parallel-safe.

**Scope:** edits only. Creation → `linear-issue-creator` or `linear-url-to-issues`.

CLI

`elnora-linear` is on `$PATH`. JSON output. Auth via `LINEAR_API_KEY`.

**The binary is `elnora-linear`, never bare `linear`.** A different, unrelated Linear CLI may own the name `linear` on `$PATH`. It is a real program, so it answers rather than failing: typically `No API key configured`. That reads like a broken setup and invites a workaround, when the only thing wrong is the name. Check with `which elnora-linear` if a command behaves oddly.

**If `elnora-linear` fails, stop and report the exact command and its output.** Do not work around it. In particular, never reach for a Linear MCP server, never read a `.env` or any other credential file, and never drive a browser to edit Linear through its web UI. A browser edit goes through a rich-text editor that silently rewrites what it is given: it has destroyed fenced code blocks in a description while reporting success.

**Long or multi-line text goes through a file, not a typed-out string.** Markdown carrying backticks, quotes and newlines is unsafe to paste into a shell argument, so hand the CLI the path and let it read the file itself (`-` reads stdin). `comments create` and `comments update` take `--body-file` the same way. Write the file as UTF-8 — any other encoding exits 2 rather than being guessed at. On Windows PowerShell use `Set-Content -Encoding utf8`, since `>` and `Out-File` default to UTF-16LE.

elnora-linear issues update ENG-123 --description-file /tmp/body.md

**After writing a description, read it back and check it.** Linear normalises markdown on save: it inserts blank lines and rewrites `-` bullets as `*`. Prose survives, but anything whitespace-sensitive may not, and the length grows. Verify the stored text, not the text you sent.

It also turns anything shaped like a link into one, which is the larger growth: a full URL `u` is stored as `[u](<u>)` (its length plus 6), and a bare domain or a file name whose extension is also a country domain (`example.com`, `prompts.py`, `reader.py:601`) as `[t](<http://t>)` (its length plus 13). When a description has a length limit, count characters, never bytes: `wc -c` counts `—`, `·` and `→` as 3 each. Count with `python3 -c "import sys; print(len(open(sys.argv[1], encoding='utf-8').read()))" body.md` (`python` on Windows), and count the stored text again after the write.

elnora-linear issues get ENG-123
elnora-linear issues search "terms" [--limit N]
elnora-linear issues update ENG-123 [--title "T"] [--description "md"] \
  [--state "S"] [--assignee "name"|"me"|"none"] [--priority 0-4] \
  [--labels "L1,L2"] [--project "P"] [--team "Team"] [--due-date "YYYY-MM-DD"]
elnora-linear teams get "Team"                # returns validStates + requiredLabels for cross-team moves
elnora-linear context --team "Team"           # full context (states, labels by prefix, requiredLabels) — use for cross-team moves
elnora-linear comments create ENG-123 --body "text"
elnora-linear comments list ENG-123
elnora-linear relations create ENG-123 ENG-456 [--type related|blocks|duplicate|similar]
elnora-linear relations list ENG-123
elnora-linear relations delete <relationId>
elnora-linear states list --team "Team Name"

**Priority:** 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low.

**Pitfalls:**

• `--labels` REPLACES — always `issues get` first, then include preserved labels in the flag.
• `--assignee` (not `--assign`); `--description` (not `--desc`); `--body` is for `comments create`, NOT issues.
• Relations are formal `IssueRelation` edges — never use a comment as a fake relation.
• **Cross-team move**: projects are team-scoped. When changing `--team`, the existing project may not exist in the target team. Either pass a `--project` valid in the target team, or unset it. Verify first with `elnora-linear projects list --team "Target"`.

Teams

Look up your workspace's teams via `elnora-linear teams list` or read `references/workspace-routing.md`.

Opportunistic metadata enrichment

When you fetch an issue to apply an edit, scan its current metadata. If you notice gaps the user didn't ask about — and they're cheap to fill — surface them and offer to fix them in the same update call:

• **Missing project** — if `project` is null and the issue clearly belongs to one, look it up cheaply via `references/workspace-routing.md` first; fall back to `elnora-linear context --team "<Team>"` if needed. Suggest adding it.
• **Missing required labels** — if the team's `requiredLabels` aren't all satisfied, suggest the missing ones.
• **Missing optional lab