Linear Cowork

Standardized Linear collaboration workflow for vibe coding teams.

MCP Setup

Before using this skill, ensure the Linear MCP server is installed and authenticated.

Quick setup for Claude Code:

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Quick setup for Codex:

codex mcp add linear --url https://mcp.linear.app/mcp

For Cursor setup and detailed instructions for all tools, see setup-guide.md in this skill directory.

Issue Conventions

Naming Rule

All issue titles MUST follow this format:

[Type] Short description

Valid types:

Examples:

• [Feature] Add OAuth login flow
• [Bug] Fix crash on empty cart submission
• [Chore] Upgrade React to v19

Bad examples (DO NOT use):

• add login — missing type prefix
• [Feature] Login — too vague, not descriptive
• Feature: add login — wrong format, must use brackets

Description Template

Every issue description MUST include these two sections:

## Background
[Why this issue exists. What problem it solves. Any relevant context.]

## Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]

Do not skip Acceptance Criteria. Even for small tasks, at least one criterion is required.

Workflow Rules

Default Assignment

When creating an issue via the Linear MCP, always assign it to "me" (the current authenticated user) unless the user explicitly specifies a different assignee.

Issue Status Lifecycle

Linear issues have 6 statuses. Proactively update issue status as the user's work progresses:

Status transition rules:

Backlog → Todo → In Progress → Done
                              → Canceled
                              → Duplicate

• Creating an issue: Set to Todo (not Backlog) unless user specifies otherwise
• User starts working on an issue: Update to In Progress
• Committing code for an issue: Update to Done
• User says to cancel/skip: Update to Canceled
• User identifies a duplicate: Update to Duplicate

Proactive status updates: When context makes it obvious (e.g., user says "I'm working on ONE-42" or "let's start ONE-42"), update the status to In Progress without needing to be asked. Similarly, when committing code linked to an issue, update to Done automatically.

Labels

Every issue MUST have a label. Choose based on the issue type:

Mapping from issue type to label:

Apply the label automatically when creating an issue — do not ask the user unless the mapping is ambiguous.

Priority

Every issue MUST have a priority set. Default to Medium (3) unless the user specifies otherwise.

Subagent Strategy

Use different models for different tasks to balance cost and quality:

Issue creation workflow:

1. Haiku    → Read Linear (check existing issues, projects, team context)
2. Explore  → Search codebase if needed (understand context for the issue)
3. Main     → Draft issue title, description, and acceptance criteria
4. Preview  → Show draft to user for confirmation
5. Haiku    → Submit to Linear after user approves

Issue update workflow:

1. Haiku    → Read current issue state from Linear
2. Main     → Determine changes needed (may explore codebase if needed)
3. Preview  → Show changes to user for confirmation (if content changes)
4. Haiku    → Apply updates to Linear

Key rules:

• Always preview issue content before submission. Show the user the full title, description, labels, priority, and status before creating or making content changes.
• Status-only updates (e.g., Todo → In Progress) do NOT need preview — apply directly.
• Simple reads and writes go through Haiku to save context tokens.
• Content that users will see (titles, descriptions, criteria) must be drafted by the main model for quality.

Project Organization

• Use Linear Projects to group related issues by feature area or milestone
• Before creating issues, check if a relevant project exists
• If no project exists and the work spans 3+ issues, create a project first

Pre-commit Checklist

Before every commit, follow this flow:

About to commit?
  ├─ Related to Linear issue?
  │   ├─ Unknown → Ask user for issue ID
  │   │   ├─ User confirms → Update status to completed, include ID in commit
  │   │   └─ No issue → Proceed with commit
  │   ├─ Yes, known → Update status to completed, include ID in commit
  │   └─ No → Proceed with commit

Steps:

1. Before committing, ask: "Is this commit related to a Linear issue? If so, which one (e.g., ONE-123)?"
2. If user provides an issue ID:
   • Use a subagent to update the issue status to Done
   • Include the issue ID in the commit message, e.g.: [ONE-123] Fix cart crash on empty submission
3. If user says no issue is related, proceed with the commit normally.

Commit Message Format with Issue ID

[ISSUE-ID] commit message

# Examples:
[ONE-42] Add OAuth login flow
[ONE-15] Fix crash on empty cart submission

Quick Reference