linear

Speed over polish. Get tickets into Linear quickly.

Do NOT explore the codebase (launch agents, read files, analyze code) unless the user explicitly asks. Work from user's description only. </objective>

<cli_reference> CLI script: ~/.agents/skills/linear/scripts/linear.py

Run with: uv run ~/.agents/skills/linear/scripts/linear.py <command> [options]

Verbose flag (-V): Available on get and list subcommands. Always use concise (no -V) unless the user explicitly needs data only verbose provides. Verbose adds URL, internal UUIDs, relations, commit SHAs, and linked documents — data that inflates context without helping most operations.

Use -V only when the user:

• Asks for the URL or link to the issue
• Needs internal IDs (team, state, project UUIDs) for API calls
• Asks about relations (blocks, blocked-by) or linked commits
• Wants to see linked documents (titles and URLs)
• Explicitly says "verbose", "full details", or "all fields"

Document awareness: Both concise and verbose modes include documentCount. When documentCount > 0, use -V to see document titles and URLs. Documents are native Linear markdown docs attached to issues via the document command.

Commands:

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

List filters:

• --mine / -m: Issues assigned to current user
• --assignee / -a: By exact assignee email, or @me for self
• --creator / -c: By exact creator email, or @me for self
• --priority / -p: By priority (0-4 or none/urgent/high/normal/low)
• --project: By project name
• --state / -s: By state name or type (backlog/todo/started/done/canceled)
• --estimate / -e: By estimate (number or 'none' for unestimated)
• --label: By label name (repeatable for AND logic)
• --cycle: By cycle number or "active" for current cycle
• --limit / -l: Max results per page (default 25)
• --after: Continue from the previous page's pageInfo.endCursor

Filters combine with AND logic. list and view-issues always return result.pageInfo. When hasNextPage is true, pass endCursor as --after with the same filters/view. Counts describe the returned page, not the total; pages are live reads, not a frozen snapshot.

T-shirt to estimate mapping:

• XS → 1, S → 2, M → 3, L → 5, XL → 8

Project handling:

• --project "Name" — Assign to project by name (overrides config default)
• --no-project — Don't assign to any project
• If neither specified, uses projectId from .linear.json if present

Label handling:

• --label "name" — Apply label by name (repeatable for multiple labels)
• --no-labels — Remove all labels (update) or skip parent inheritance (break)
• On create: if no --label and no parent labels are inherited, applies defaultLabels from .linear.json
• On update: --label replaces all existing labels
• On break: sub-issues inherit parent labels by default </cli_reference>

{
  "teamId": "uuid-of-linear-team",
  "projectId": "uuid-of-linear-project (optional)",
  "defaultPriority": 3,
  "defaultLabels": ["mobile"]
}

• teamId — Your Linear team UUID. Only needed in the file if you rely on .linear.json to pick the team (see below).
• projectId — Optional. Default project for new issues. Can be overridden with --project or --no-project.
• defaultLabels — Optional. Label names auto-applied on create when --label is not specified.

Team resolution. When create or update needs a team for creation or for resolving team-scoped names (--label, --project, --cycle), it resolves in this order and stops at the first hit:

1. --team <key-or-uuid> flag — accepts a team key like ENG or a raw UUID
2. LINEAR_TEAM env var (key or UUID)
3. the issue's / parent's own team — update and create --parent derive this from the target/parent issue, so they need no config and no --team for those flows
4. .linear.json teamId
5. single-team auto-detect — if the workspace has exactly one team, it is used automatically

break always creates sub-issues in the parent issue's team because Linear ties sub-issues to their parent team. It needs no config and ignores unrelated team defaults; use the parent's own project/labels or explicit --project/--label overrides that resolve within the parent team.

A single-team workspace needs no config at all for commands that use this resolver (create, update name resolution, and list filters that require a team such as named states/cycles). Standalone list can remain workspace-wide without a team. In a multi-team workspace, standalone create needs one of --team / LINEAR_TEAM / .linear.json (or it errors listing the available team keys).

When .linear.json is present but the team is overridden to a different team (via --team/LINEAR_TEAM/parent issue), the file's defaultPriority/defaultLabels still apply but its projectId is dropped (it is scoped to the file's team). A defaults-only .linear.json without teamId is allowed when a higher-precedence team source selects the team.

API key: Set LINEAR_API_KEY in project's .claude/settings.local.json (git-ignored by default):

{
  "env": {
    "LINEAR_API_KEY": "lin_api_..."
  }
}

Issue ID pattern: 2-4 uppercase letters followed by hyphen and numbers (e.g., ABC-123, PROJ-42).

Issue deletion: Only delete an explicitly requested ticket; never infer deletion from cancellation, completion, or duplicate status. delete is non-interactive and moves the issue to Linear's trash, recoverable from the team's Recently deleted issues for 30 days before permanent removal. It does not offer immediate permanent deletion. It needs no project config or team selection. Do not retry an uncertain deletion automatically; check Linear first.

Comment vs document vs attach vs attach-commit decision:

Combined actions: "mark as done and add the commit" → done + attach-commit. "mark as done and leave a comment" → done + comment.

When ambiguous between comment and document, prefer comment.

Comment quality — what to write:

Focus on decisions, blockers, surprises, and state changes — not mechanical change inventories ("updated file X, changed Y to Z") visible in diffs. Extract the insight, not the inventory.

Good: "Switched from polling to SSE — polling hit rate limits under load. Estimate unchanged since the SSE client is already in the codebase." Bad: "Updated api.py to use SSE instead of polling. Changed the import on line 12. Added error handler on line 45."

Scope-change awareness — re-evaluate priority and estimate:

When adding a comment or updating a ticket's description that changes the scope of work (new ideas, expanded requirements, refined approach), always consider whether the priority and estimate still fit. Users often brainstorm on existing tickets — capturing new ideas via comments or rewriting descriptions — without explicitly thinking about how this affects sizing.

• After writing a comment or updating a description that changes scope, check the current priority and estimate
• If the new content meaningfully expands or narrows the work, adjust priority and/or estimate in the same update call
• Mention the adjustment in the output (e.g., "Bumped estimate S→M to reflect expanded scope")
• If scope changed but priority/estimate still fit, no action needed — don't adjust for the sake of it</step>

The CLI's --assignee accepts only an exact email or the @me sentinel. Fuzzy intent resolution happens here, at the skill layer — never rely on the CLI to guess.

1. Self-assignment — if the user means themselves ("assign to me", "for me", "my ticket"), pass --assignee @me directly. Do not run members.
2. Otherwise, run members to fetch the active member list.
3. Fuzzy match the requested name in-context against name, displayName, and email.
4. If exactly one match, pass --assignee <email> (the email, not the name).
5. If multiple matches, use AskUserQuestion to disambiguate with the matching names as options, then pass the chosen user's email.
6. If no match, show available members and ask the user to clarify.</step>

Execute CLI and format output.

uv run ~/.agents/skills/linear/scripts/linear.py [command] [args]

Long Markdown: Use create/update --description-file path or comment/update-comment --body-file path instead of shell interpolation. Files are UTF-8 and sent unchanged; file and inline inputs are mutually exclusive. An empty description file clears the description on update.

Partial edits: Fetch the current text before replacing it; preserve unchanged sections. For multi-issue work, keep successful receipts and retry only failed operations, not the whole batch. After an uncertain create/comment outcome, check Linear before retrying to avoid duplicates.

Round trips: Linear may normalize bullets, blank lines, and email links; these alone do not indicate lost content. If an angle-bracket link is rejected, convert [text](<URL>) to [text](URL), encoding spaces and parentheses in the destination. Preserve the URL—do not strip the link.

Parse JSON response and present result:

• Success: Show identifier, title, new state, and URL
• For delete: Show identifier and title, and report moved to trash (recoverable for 30 days), not a workflow-state change.
• For projects/labels: List grouped by team
• Error: Show error message and suggestions</step>

1. Parse input for hints:
   • Title from first sentence or quoted text
   • Priority hints: "urgent", "high priority", "low priority", "blocker"
   • Estimate hints: "XS", "S", "M", "L", "XL", "small", "medium", "large"
   • Parent ID if pattern <ID> <description>
   • Project hints: "in [Project]", "for [Project]", "(project: [Name])", "[Project] project"

2. Infer project and labels from the description:

   Run projects and labels to fetch available options (cache across the session — don't re-fetch if already retrieved this conversation).

   Project inference:

   • If user explicitly named a project in their message → use it
   • Otherwise, match the ticket's domain/area against available project names and descriptions
   • If exactly one project is a clear match → pre-select it (confirm in step 4)
   • If multiple plausible matches or no match → include project selection in step 4's AskUserQuestion
   • If no projects match and the ticket represents a new area of work → include a "Create new project: [suggested name]" option in step 4

   Label inference:

   • If user explicitly named labels → use them
   • Otherwise, match against available labels by category (e.g., platform, area, type)
   • Pre-select labels that clearly apply (confirm in step 4)
   • If the ticket's domain suggests a label that doesn't exist → include a "Create label: [suggested name]" option in step 4
   • defaultLabels from .linear.json apply when no explicit or inherited labels are used; if you pass --label, include every desired label

3. Infer priority and estimate from the description:

   Priority inference — based on user impact:

   Priority reflects how many users are affected and how central the affected flow is to the product. Not how hard the fix is (that's what estimate captures).

   Score by asking: how many users benefit, how central is this to what makes the product valuable, and does it move a success metric (engagement, growth, retention, monetization)?

   Priority	Bugs / Issues	New Features / Improvements
   Urgent (1)	Broken core flow. Most users hit this. Blocked, losing data, cannot work around it.	Rare for features. Only if a critical gap is actively causing churn or blocking a launch.
   High (2)	Degraded core flow OR broken secondary flow. Core flow works but with significant friction or incorrect behavior. OR a regularly-used secondary flow is broken.	Strengthens the core USP. Directly tied to the product's unique value proposition or the core problem it solves. Benefits most users. Likely to drive engagement, retention, or growth.
   Normal (3)	Non-critical bug. Affects a moderate number of users or a less common flow. Workaround exists.	Meaningful improvement. Elevates an existing flow or adds a useful capability. Benefits a decent user segment. Improves satisfaction but not directly tied to the core differentiator.
   Low (4)	Edge case or cosmetic. Small subset of users, rare trigger, visual-only.	Peripheral or niche. Benefits few users, adds to a rarely-used flow, or is a nice-to-have that doesn't move a success metric.

   Quick signals (disambiguation beyond the table):

   • "Users can't ___" → Urgent or High
   • "Users have to work around ___" → High
   • "This would make ___ much better" → Normal
   • "Sometimes when ___ happens" (edge case) → Low
   • "It would be nice if ___" → Low
   • Feature that drives engagement/retention/monetization → bump up one level

   Estimate inference — calibrated for Claude Code development:

   Estimates reflect effort when Claude Code does the implementation. Repetitive refactoring across files may be easy for AI; work needing context discovery may be harder.

   Estimate	Criteria	Effort signals
   XS (1)	1 file, clear fix, no ambiguity. Config change, typo fix, remove dead code.	Isolated, no downstream consumers, additive only
   S (2)	1-2 files, known approach. Single-file rewrite, pure research/audit with no code changes.	Known approach, clear root cause
   M (3)	2-5 files, known approach but coordination needed. Template + references update, new agent mirroring existing pattern.	Some coordination, one obvious approach
   L (5)	5+ files, OR requires investigation, OR replaces existing functionality. New command with workflow, multi-file migration.	Investigation required, multiple valid approaches, breaking changes
   XL (8)	Architectural change, OR 8+ files, OR fundamentally changes a major system part. New subsystem, cross-cutting refactor, deprecating multiple commands.	Core path with many dependents, fundamentally changes major system

   Quick signals:

   • Pure research/audit (no code changes) → cap at S (2)
   • Root cause already known (in comments/description) → reduce by one size
   • "Evaluate whether" / "investigate" → at least M (3) for the decision overhead
   • Replacing N existing commands/workflows → at least L (5)
   • Parent ticket with sub-issues → remove estimate from parent (sub-issues carry their own)

4. Check for "problem to solve":

   If the user only provided implementation details (e.g., "add a retry flag to the API call") without a user-facing problem, ask: "What's the problem you're solving from a user perspective?" before proceeding. The answer becomes the ticket's core framing.

   Skip this check if the user already stated a problem (e.g., "users lose data when the connection drops").

5. Ask UP TO 4 questions in ONE AskUserQuestion call:

   Combine these into a single batch:

   Confirmation question: Show inferred priority/estimate and inferred project/labels, ask to confirm or adjust

   Project/label question (if needed):

   • If project is ambiguous or unmatched → list matching projects as options, include "Create new project: [name]" if appropriate
   • If labels need confirmation or a new label is suggested → list as multi-select options, include "Create label: [name]" for new ones
   • If project and labels were confidently inferred → just show them in the confirmation question, no separate question needed

   High-impact domain questions (pick 1-2 most relevant):

   • Scope clarification: "Should this [specific behavior] or [alternative]?"
   • Edge cases: "What should happen when [edge case]?"
   • Acceptance criteria: "What's the minimum for this to be done?"
   • Context: "Is this related to [existing feature/area]?"

   Skip questions with obvious answers from description. If description is very clear, may only need confirmation.

6. Create immediately after answers:

   If user approved creating a new project or label, create it first via create-project or create-label, then use the result in the create command.

   Structure the description as:

   ## Problem
   [1-2 sentences: the user-facing problem or need]
   
   ## Solution
   [1-3 sentences: what this ticket delivers]
   
   ## Details
   - [Key requirements or constraints from user's answers]

   Omit ## Details if there's nothing beyond what Problem/Solution already covers. Keep it concise — a few lines beats a wall of text.

   A description states the observed problem, the agreed outcome as an invariant, and pointers to evidence. It does not prescribe mechanisms, list scenarios per role, environment, platform or call site, or enumerate what not to build; one boundary sentence is enough. Name platform or device checks only when the code branches on platform.

   uv run ~/.agents/skills/linear/scripts/linear.py create "[title]" \
     -d "[structured description]" -p [priority] -e [estimate] \
     [--parent ID] [--project "Name"] [--label "name"] [--no-project] \
     [--cycle <number-or-"active">]

7. Format result:

   Created: **[identifier]** — [title]
   Project: [project name] | Labels: [label1, label2]
   [url]

User provides the sub-issues in conversation. Do NOT propose or generate sub-issues.

1. Get sub-issue list from user (they specify titles/estimates in their message)

2. Build JSON and execute:

   uv run ~/.agents/skills/linear/scripts/linear.py break [ID] \
     --issues '[{"title":"...","estimate":3},{"title":"...","estimate":2}]'

3. Format result:

   Created N sub-issues under [parent-identifier]:
   - **[ID-1]** — [title 1]
   - **[ID-2]** — [title 2]

• MISSING_API_KEY: Explain how to set LINEAR_API_KEY in project .claude/settings.local.json
• MISSING_CONFIG: For resolver-backed flows, this means a multi-team workspace has no team selected. Tell the user to pass --team KEY, set LINEAR_TEAM, or create .linear.json; the error lists the available team keys. Some management commands still require .linear.json directly and will say so.
• TEAM_NOT_FOUND: The --team/LINEAR_TEAM ref matched no team. List the available team keys from the error suggestions.
• ISSUE_NOT_FOUND: Suggest checking the identifier
• STATE_NOT_FOUND: List available states from states command
• PROJECT_NOT_FOUND: List available projects from projects command
• LABEL_NOT_FOUND: List available labels from labels command
• CYCLE_NOT_FOUND: Suggest using cycles to see available cycles
• VIEW_NOT_FOUND: List available views from views command
• FILE_NOT_FOUND: Suggest checking the file path
• UPLOAD_FAILED: Suggest retrying or checking connectivity

Always parse JSON error response and present human-friendly message with suggestions. </step>

<success_criteria>

• No codebase exploration unless user explicitly requests it
• Create flow infers project and labels from available options before asking questions
• Create flow asks max 4 questions in ONE AskUserQuestion call
• Issue created immediately after user answers questions
• Errors handled with helpful suggestions
• Direct commands execute immediately without questions
• CLI output parsed and formatted for readability </success_criteria>