claude-linear-workflow

Linear Workflow Plugin for Claude Code

A Claude Code plugin that enforces Linear issue-tracked development workflow with branch naming conventions, Conventional Commits validation, and automatic issue tracking.

Features

• Branch enforcement: Blocks implementation without a Linear issue and related branch
• Commit validation: Enforces Conventional Commits format
• Seamless Linear sync: Works with existing issues or creates new ones on the fly-either way, Linear stays in sync
• Consistent shared context with Linear issue tracking: Logs progress to Linear issue comments - one source of truth across sessions and teammates

Prerequisites

• Claude Code CLI
• GitHub + Linear integration - enables PR auto-linking and issue status sync on merge
• Git repository

Installation

# 1. Add marketplace
/plugin marketplace add bahamoth/claude-marketplace
# Or host your own marketplace - see https://code.claude.com/docs/en/plugin-marketplaces

# 2. Install plugin
/plugin install linear-workflow@bahamoth/claude-marketplace

# 3. Enable plugin
/plugin enable linear-workflow

# 4. Authenticate Linear MCP (opens browser for OAuth)
/mcp linear-mcp auth

Configuration

Add your Linear team to .claude/settings.json:

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

Variable	Required	Description
LINEAR_WORKFLOW_TEAM	Yes	Your Linear team name
LINEAR_WORKFLOW_PROJECT	No	Project for new issues (Backlog if omitted)

If LINEAR_WORKFLOW_TEAM is not configured, the plugin will block implementation and guide you to set it up.

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

1. Starting Work

When you try to exit plan mode on main, the plugin blocks and guides you to:

1. Search Linear for existing issues
2. Create a new issue if needed
3. Create a branch using Linear's gitBranchName

2. Branch Naming

Use the gitBranchName field from the Linear issue:

git checkout -b <gitBranchName>

Branch format is configured in Linear: Settings > Workspace > Integrations > Branch format

3. Commit Messages

Follow Conventional Commits format:

type(scope): description

Refs ABC-123

Format: type(scope): description where type is any lowercase word (commonly feat, fix, docs, refactor, etc.)

4. Pull Requests

Include Linear magic words to auto-close issues:

Fixes ABC-123

Hooks

Hook	Event	Matcher	Purpose
check_linear_env.py	UserPromptSubmit	-	Early warning if env not configured
check_linear_env.py	PreToolUse	Write|Edit|ExitPlanMode	Re-check env before implementation
ensure_linear_branch.py	PreToolUse	Write|Edit|ExitPlanMode	Enforce Linear branch before changes
validate_commit_msg.py	PreToolUse	Bash	Validate Conventional Commits
Prompt	PreCompact	-	Sync progress to Linear comments

License

MIT