linear-expert

Linear Expert

Master-level expertise in Linear configuration, workflow design, GraphQL API mastery, Cycle and Project management, Initiative-level roadmaps, triage automation, GitHub integration, and migration from Jira. Covers everything from workspace setup to programmatic bulk operations against the Linear API.

Overview

Linear is an opinionated, keyboard-driven issue tracker built around a strict data model (Team → Project → Issue → Sub-issue) and a GraphQL-only public API. Unlike Jira, Linear's strength is its lack of configurability: there is one workflow shape (Backlog → Unstarted → Started → Completed → Canceled), one priority scale (0-4), and a tight set of first-class concepts (Cycles, Projects, Initiatives, Labels, Milestones). The job of a Linear expert is to operate fluently inside those rails while extending the system through the API, automations, and integrations.

Core Capabilities

• Workspace & team configuration — URL keys, SSO, team keys, cycle cadence, estimation scales, workflow states, label taxonomy
• Planning hierarchy — Cycles (sprints), Projects + Milestones, Initiatives, and Roadmap views
• Triage automation — inbound routing from Slack, support, GitHub Issues; daily triage SOP
• GraphQL API mastery — query/mutation authoring, pagination, batch mutations, webhooks, rate-limit hygiene
• GitHub integration — magic-word auto-link/auto-close, branch auto-linking, PR-state syncing
• Bulk operations & migration — API-driven bulk edits and Jira → Linear migration planning

When to Use

• Setting up a new Linear workspace, team, or project from scratch
• Designing Cycle cadence, triage rules, and SLA workflows
• Writing GraphQL queries and mutations against the Linear API
• Configuring GitHub PR auto-link/auto-close and Slack notifications
• Building Initiative / Project / Milestone hierarchies for executive roadmaps
• Running bulk operations (relabel, retarget, reassign) across hundreds of issues
• Migrating an existing Jira instance to Linear without losing history
• Diagnosing why automations, sub-issues, or triage rules are not firing as expected

Quick Start

Linear's API is GraphQL-only at https://api.linear.app/graphql; auth via personal API key (Authorization: <key>) or OAuth2.

linear_query() {
  curl -s -X POST https://api.linear.app/graphql \
    -H "Authorization: $LINEAR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"query\": \"$1\"}"
}

Cache team/label/state UUIDs locally, use nested selection to avoid N+1 calls, and prefer webhooks over polling. See the references below for the full query catalog and operating workflows.

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• references/linear-concepts-and-workflows.md — Linear data model, the 7 core workflows (setup, cycle/project planning, initiatives, triage, GitHub, bulk ops, Jira migration), best practices, and success criteria. Read when configuring a workspace or running any of the core operating workflows.
• references/linear-graphql-patterns.md — canonical query and mutation catalog with variables, plus inline quick examples and CLI patterns. Read when authoring any GraphQL query/mutation or scripting against the API.
• references/linear-vs-jira.md — concept-by-concept translation guide for teams migrating from Jira. Read before planning a Jira → Linear migration.
• references/red-flags.md — common anti-patterns (cycle-as-sprint, project bloat, N+1, untriaged inbox, unsigned webhooks) plus the troubleshooting table. Read before applying config/queries to a team or when diagnosing failures.
• assets/linear-team-template.md — recommended new-team configuration. Read when standing up a new team.
• assets/linear-triage-workflow.md — daily triage SOP and rotation template. Read when staffing or designing triage.
• Linear API docs: https://developers.linear.app/docs
• Linear GraphQL schema explorer: https://studio.apollographql.com/public/Linear-API/
• Linear method (workspace conventions): https://linear.app/method

Scope & Limitations

In Scope: Linear workspace, team, and project configuration; cycle and project planning; Initiative and Roadmap hierarchy; triage workflow design; GitHub PR integration; GraphQL query and mutation authoring; bulk operations via API; webhook configuration; Jira → Linear migration planning and execution.

Out of Scope: Jira-side configuration and migration freeze (hand off to jira-expert/); Notion documentation pages for Linear roadmaps (hand off to notion-pm/); strategic prioritization and OKR setting (hand off to senior-pm/, execution/brainstorm-okrs/); sprint coaching and team health (hand off to scrum-master/); release notes generation from Linear issues (hand off to execution/release-notes/).

Limitations: Linear has no custom fields; all extension happens through labels, descriptions, or external systems. The free tier caps at 250 issues per workspace and excludes Initiatives and SAML. API rate limits are workspace-wide and shared across all keys; heavy automation may require coordination. Importers preserve most history but cannot recreate Jira's custom workflow states; mapping is many-to-five. GraphQL schema evolves continuously; pin client code to the deprecation calendar.

Integration Points