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:

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

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

Action	Command
Get issue	`mcp__linear-server__get_issue(id: "{PREFIX}-XX")`
Update status	`mcp__linear-server__update_issue(id: "{PREFIX}-XX", state: "In Progress")`
Add comment	`mcp__linear-server__create_comment(issueId: "{PREFIX}-XX", body: "...")`
Create issue	`mcp__linear-server__create_issue(title: "...", team: "{TEAM}", project: "{PROJECT}")`

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:

Branch Example	Valid?
`feature/ABC-123-auth`	Yes
`john/ABC-123-auth`	Yes
`ABC-123-auth`	Yes
`ABC-123`	Yes
`main`	No (protected)
`feature/auth`	No (no issue ID)

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

Status	When to Use	Transition
Backlog	Initial state, not yet prioritized	Auto
Todo	Ready for work	Manual
In Progress	Actively working	Set at branch creation
In Review	PR created, awaiting review	Set at PR creation
Done	PR merged	Auto (via `Fixes {PREFIX}-XX`)

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):

Type	Usage	SemVer Impact
`feat`	New feature	MINOR bump
`fix`	Bug fix	PATCH bump
`feat!:`	Breaking change (add ! suffix)	MAJOR bump

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

Keyword	Effect
`closes`, `fixes`, `resolves`, `completes`	Close issue on PR merge
`refs`, `part of`, `related to`	Link only, no status change

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

linear-workflow