Linear

Linear hosts no code. It has no repositories, branches or pull requests, so a Linear project always declares a separate code host (usually GitHub). This is pair's reference split setup, see Code host vs PM tool for the routing rule and cross-linking convention.

Why Linear is the page that changed pair's design

Linear is the tool that broke the assumption everything else in pair had been built on: that the one pm-tool field could answer both backlog work and code work (the PM tools overview tells that story in full). Linear answers exactly one of the two, and asking it for a pull request is asking a backlog for something it does not have.

The obvious fix was the wrong one. Linear ships an excellent GitHub app that would have supplied the item↔PR link for free and pushed PR status onto the card. It was rejected (per ADR-018) for two reasons: it would make a proprietary per-tool integration a hard prerequisite of the framework, so every future tracker would need its own porting story and air-gapped setups could not comply; and it duplicates state across two systems, which is fine until one write fails and there is no owner to reconcile from.

What pair adopted instead is deliberately unglamorous, and it is why this page reads the way it does:

• One optional field. Declare code-host in ## Git Workflow and issue/state work routes to Linear while branch/PR/review work routes to GitHub. Projects already on a single tool declare nothing and behave exactly as before.
• The cross-link is plain text, both ways. Refs: <issue-id> in the PR body; the PR URL posted back as a comment on the Linear issue: a comment, never a body edit, because writing the body would overwrite the story's acceptance criteria. Any tool with a comment field can play.
• PR state (draft / ready / approved / merged) is never mirrored onto the board. Macrostate transitions still happen on Linear: the Status Transitions table below moves the issue to "In Review" when the PR opens, on teams that have that state (see the table). What never crosses is the pull request's own state: find the row whose Linear column says nothing happens, review. It happens entirely on the code host. That "nothing" is the decision, not an omission: each state lives in one place, so there is nothing to reconcile.
• What Linear does not have, pair reports rather than invents. Linear's default teams ship no "In Review" state; a skill asked to write one says so instead of guessing a nearby column.

The rest of this page is the configuration that model implies, including the one section a single-tool guide has no need for: ## Git Workflow, where the code-host is declared.

Configuration

Add these lines to .pair/adoption/tech/way-of-working.md:

- Linear is adopted for project management.
  Team: <your-team-key>. Project: <your-project-name>.
  Access: Linear MCP Server (fallback: GraphQL API).
  See `.pair/knowledge/guidelines/collaboration/project-management-tool/linear-implementation.md` for usage.
 
## Git Workflow
 
- `code-host`: `github` - repository `<org>/<repo>`.
- `base-branch`: `main`.

Issue and state operations go to Linear; branch, PR, review and merge operations go to the code host. The two are linked by Refs: <issue-id> in the PR body plus the PR URL commented back on the Linear issue: no native integration required.

Prerequisites

• Linear account with a team and project created
• Linear API key (Settings → Account → Security & access → Personal API keys)
• One access path: Linear MCP Server, or direct GraphQL API access
• A code host for the repositories, declared as code-host

Linear MCP Server

pair's AI assistants use the Linear MCP Server to interact with Linear programmatically. This enables creating issues, updating statuses, and querying project state for /pair-next recommendations.

Configure the MCP server with your Linear API key following your AI tool's MCP setup guide.

Mapping Model

pair maps its work hierarchy to Linear concepts:

pair                    Linear
────                    ──────
Initiative          →   Project (or label-based grouping)
Epic                →   Issue (parent)
User Story          →   Sub-issue
Task                →   Checklist item in story issue body

How It Works

• Initiatives map to Linear Projects or are tracked via labels, depending on team preference
• Epics are top-level Linear Issues
• User Stories are sub-issues under their parent epic
• Tasks are checkbox items in the story issue description, not separate issues
• Status tracking uses Linear's workflow states (Backlog, Todo, In Progress, Done)

Status Transitions

State transitions always happen on Linear. PR states (draft / ready / approved / merged) live on the code host and are never mirrored onto Linear, so no state is duplicated.

Labels and Properties

pair uses Linear's built-in features:

First-Run Example

After configuring way-of-working.md, run a process skill:

/pair-process-plan-stories #42    # break epic #42 into stories

Expected output:

STORIES CREATED:
├── LIN-101: As a user, I want to sign up so that I can access the platform
├── LIN-102: As a user, I want to log in so that I can see my dashboard
├── LIN-103: As a user, I want to reset my password so that I can recover access
└── Epic LIN-42: 3 stories created, all set to "Backlog"

pair creates Linear sub-issues under the epic, sets priority, and assigns them to your team.

Verifying the Setup

1. Open your Linear team's board
2. Verify new issues appear in "Backlog"
3. Each sub-issue should reference its parent epic
4. Priority and labels should match pair's configuration

Related

• Code host vs PM tool: the split setup, routing rule and cross-linking convention
• Canonical states: mapping Linear workflow states to macrostates
• PM Tools overview: choosing the right tool
• Filesystem: zero-PM-dependency alternative (backlog in your repo; still declares a code-host)
• GitHub Projects: GitHub-native option