Linear Workflow

Linear-Tracked Development Workflow

Prerequisites

Linear MCP: Configure in MCP settings:

{
  "mcpServers": {
    "linear": {
      "command": "mcp-remote",
      "args": ["-y", "https://mcp.linear.app/mcp"]
    }
  }
}

gh CLI: Install and authenticate:

brew install gh  # or: https://cli.github.com/
gh auth login

Configuration

This skill requires Linear MCP to be configured. On first use:

1. Check environment variables in .claude/settings.json:

   • If LINEAR_WORKFLOW_TEAM and LINEAR_WORKFLOW_PROJECT exist → use them
   • If not → guide user to set them up before proceeding

2. Get issue prefix dynamically:

   mcp__linear-server__list_issues(team: "{LINEAR_WORKFLOW_TEAM}", limit: 1)
   # Extract prefix from identifier (e.g., "ABC-34" → "ABC")
   

Example settings.json

{
  "env": {
    "LINEAR_WORKFLOW_TEAM": "YourTeam",
    "LINEAR_WORKFLOW_PROJECT": "YourProject"
  }
}

Note: issuePrefix is auto-detected from Linear, no manual config needed.

Auto-Activation Triggers

• Starting code implementation
• File modifications on main/master without issue branch
• Mentioning a Linear issue ({PREFIX}-XX) in conversation
• Creating commits with Conventional Commits format
• Creating a PR with Fixes {PREFIX}-XX

Workflow Overview

Has Issue                    No Issue
    │                            │
    ▼                            ▼
Query via MCP          Plan → Create Issue in Linear
    │                            │
    └──────────┬─────────────────┘
               ▼
    Create branch (use gitBranchName)
               ▼
    Linear status: In Progress + start comment
               ▼
    Work (comment on decisions/blockers)
               ▼
    Create PR (Fixes {PREFIX}-XX)
               ▼
    Merge (rebase-ff) → Linear auto-Done

Quick Reference

1. Check or Create Issue

Case A: Starting with Existing Issue

# Query issue via MCP
mcp__linear-server__get_issue(id: "{PREFIX}-XX")

• Use gitBranchName field as branch name
• Check Acceptance Criteria in issue description

Case B: Starting without Issue

After planning, before implementation, create Linear issue using this template:

mcp__linear-server__create_issue(
  title: "Concise work title",
  description: "<issue description template below>",
  team: "{LINEAR_WORKFLOW_TEAM}"
)

If LINEAR_WORKFLOW_PROJECT is configured: Add project: "{LINEAR_WORKFLOW_PROJECT}" parameter.

Issues without a project are created in the team's Backlog.

Issue Description Template

## Objective

[One sentence describing what this work achieves]

## Background

- [Why this work is needed]
- [Context or constraints]
- [Related prior work or decisions]

## Implementation Approach

- [High-level approach or strategy]
- [Key technical decisions]
- [Files/components to modify]

## Acceptance Criteria

- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]

Guidelines:

• Objective: Single sentence, action-oriented (e.g., "Add logging infrastructure for LLM debugging")
• Background: 2-4 bullet points explaining why, not how
• Implementation Approach: Technical strategy, not step-by-step instructions
• Acceptance Criteria: Checkboxes, testable conditions for "done"

2. Create Branch

Use the gitBranchName field from the Linear issue directly:

# Get issue details (gitBranchName is included in response)
mcp__linear-server__get_issue(id: "{PREFIX}-XX")

# Create branch using gitBranchName value
git checkout -b <gitBranchName>

Branch Format: Configured in Linear at Settings > Workspace > Integrations > GitHub/GitLab > Branch format. The gitBranchName field reflects your team's configured format.

Branch Validation

This workflow validates branch names loosely—only requiring a Linear issue ID (e.g., ABC-123). This allows teams to use any branch format configured in Linear:

3. Update Status + Start Comment

# Update status
mcp__linear-server__update_issue(id: "{PREFIX}-XX", state: "In Progress")

# Start comment (use actual branch name)
mcp__linear-server__create_comment(
  issueId: "{PREFIX}-XX",
  body: "## Started\n\n- Branch: `<branch-name>`\n- Implementing ..."
)

Linear Status Transitions

4. Comments During Work

Write comments for major decisions, progress updates, or blockers.

Language: English only (for global team collaboration)

Progress Update

## Progress Update

- Completed: [what was done]
- In Progress: [current work]
- Next: [upcoming tasks]

Technical Decision

## Decision: [title]

**Context**: [why this decision was needed]

**Options considered**:

1. [Option A] - pros/cons
2. [Option B] - pros/cons

**Chosen**: [option] because [reason]

Blocked

## Blocked

**Issue**: [description]
**Waiting on**: [dependency/person]
**Workaround**: [if any]

5. Commit Rules

Conventional Commits + Linear reference:

git commit -m "feat(scope): implement feature

Refs {PREFIX}-XX"

Commit Types

SemVer-relevant (required for versioning):

Other common types:

docs, refactor, test, chore, style, perf, ci, build, revert, or any lowercase word that fits the change.

Linear Reference Keywords

• Refs {PREFIX}-XX: Link only (no status change)
• Closes {PREFIX}-XX: Auto-close issue on PR merge

6. Create PR

PR Title

Conventional Commit format:

feat(linear): add workflow skills

PR Body

## Summary

- [Change 1]
- [Change 2]

## Test Plan

- [ ] Test item 1
- [ ] Test item 2

Fixes {PREFIX}-XX

PR Creation Command

gh pr create --title "feat(scope): description" --body "$(cat <<'EOF'
## Summary
- ...

## Test Plan
- [ ] ...

Fixes {PREFIX}-XX

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

7. Merge

GitHub standard method (rebase-ff):

# After PR approval
gh pr merge --rebase

Linear detects Fixes {PREFIX}-XX → auto-closes issue as Done

Linear Magic Words Reference

Workflow Checklist

Copy this checklist and check off items as you complete them:

Linear Workflow Progress:

Starting Work:
- [ ] Check if issue exists (create if not)
- [ ] Create branch using `gitBranchName`
- [ ] Status → In Progress
- [ ] Write start comment

During Work:
- [ ] Comment on major decisions/blockers
- [ ] Follow Conventional Commits
- [ ] Include `Refs {PREFIX}-XX` in commits

On Completion:
- [ ] Create PR (include `Fixes {PREFIX}-XX`)
- [ ] Request code review
- [ ] Merge (rebase-ff)
- [ ] Verify Linear auto-Done

Converted and distributed by TomeVault — claim your Tome and manage your conversions.