Linear Workflow

Automate the complete development workflow with Linear issue tracking, from task start to merge completion.

Overview

This skill provides end-to-end workflow automation:

1. Mandatory Linear verification - All Linear operations are verified
2. Issue creation/selection with validation
3. Branch management
4. Local state persistence - Task state saved to .claude/linear-tasks/<ISSUE_ID>.json
5. Status synchronization
6. PR creation with CI monitoring
7. Merge and cleanup

Key Features

• Mandatory Linear Connection: The /yux-linear-start command will FAIL if Linear MCP is not configured or unavailable
• Issue Verification: Every issue creation/selection is verified via mcp__linear__get_issue()
• Local State Files: Task state is persisted to .claude/linear-tasks/ directory (tracked by git)
• Session Detection: New sessions automatically detect current Linear task context

Configuration

Before generating output, read .claude/yux-config.json:

• If language is set, output in that language
• If file doesn't exist, detect from user input or default to English
• Load messages from templates/messages.json for the configured language

Initialize config with /yux-init if not exists.

Local State File

Each Linear task has a corresponding state file in .claude/linear-tasks/:

File format: .claude/linear-tasks/<ISSUE_ID>.json

Example: .claude/linear-tasks/LIN-456.json

{
  "issue_id": "LIN-456",
  "issue_uuid": "cfef1fd0-...",
  "issue_title": "Implement user authentication",
  "branch_name": "feat/LIN-456-user-auth",
  "status": "in_progress",
  "linear_url": "https://linear.app/team/issue/LIN-456",
  "started_at": "2026-01-09T10:30:00Z",
  "verified": true
}

Git tracking: These files are committed to git, ensuring state persists across branches and sessions.

Workflow States

State	Linear Status	Description
INIT	-	Workflow not started
ISSUE_CREATED	Backlog	Issue created, no branch
BRANCH_CREATED	Todo	Branch created, ready to work
IN_PROGRESS	In Progress	Active development
PR_CREATED	In Review	PR submitted, awaiting review
CI_RUNNING	In Review	CI checks in progress
CI_FAILED	In Progress	CI failed, needs fix
READY_TO_MERGE	In Review	All checks passed
MERGED	Done	PR merged, task complete

Core Functions

1. Start Task

When user wants to start a new task:

1. MANDATORY: Verify Linear connection:

   mcp__linear__list_teams()
   

   • If this fails, STOP immediately and guide user to configure Linear
   • Do NOT proceed without a working Linear connection

2. Check other prerequisites:

   gh auth status
   git rev-parse --is-inside-work-tree
   

3. Search or create Linear issue:

   • Use mcp__linear__list_issues for search
   • Use mcp__linear__create_issue for new issues

4. MANDATORY: Verify issue exists:

   mcp__linear__get_issue(id: "<issue-uuid>")
   

   • If verification fails, STOP and report error

5. Create branch:

   • Format: <type>/LIN-<id>-<description>
   • Types: feat, fix, docs, refactor, test, chore

   git checkout -b <branch-name>
   git push -u origin <branch-name>
   

6. Update Linear status:

   mcp__linear__update_issue(id: "<issue-uuid>", state: "In Progress")
   

7. Save local state file:

   mkdir -p .claude/linear-tasks
   # Write state to .claude/linear-tasks/<ISSUE_ID>.json
   

2. Development Tracking

During active development:

1. Validate commits follow Conventional Commits:

   • Pattern: <type>(<scope>): <description>
   • Valid types: feat, fix, docs, style, refactor, test, chore, perf

2. Sync progress periodically:

   • Add comments to Linear issue with progress updates
   • Track blockers and decisions

2.5 Stage Commit (/yux-linear-commit)

For incremental commits during development:

1. Show changed files categorized by type (new/modified/deleted)
2. Let user select files to commit (not automatic)
3. Atomic check - Suggest splitting if multiple unrelated changes detected
4. Auto-generate commit message (user input is reference only)
   • Claude analyzes changes and generates appropriate message
   • Format with emoji prefix:

   <emoji> <type>(<scope>): <subject>
   
   **What**
   - Specific changes made
   
   **Why**
   Explanation of motivation
   
   Refs: LIN-xxx
   
   **Who**
   Co-Authored-By: wuyuxiang 🤖 Generated by Claude AI
   

   Note: Output language follows .claude/yux-config.json setting.

5. Execute commit - Only git add and git commit, NOT git push
6. MANDATORY: Sync to Linear - Add comment to issue recording the commit

Emoji mapping:

Type	Emoji	Type	Emoji
feat	✨	fix	🐛
docs	📝	style	💄
refactor	♻️	perf	⚡️
test	✅	chore	🔧

Key points:

• Output language follows .claude/yux-config.json setting
• Every commit is recorded to Linear (not optional)
• Sensitive files (.env, credentials) are flagged for review
• Commit message is auto-generated, user input only serves as reference
• User manually runs git push after commit

3. Create Pull Request

When ready for review:

1. Generate PR content:

   • Title: [LIN-xxx] <Issue Title>
   • Body: Summary + changelog + test plan

2. Create PR:

   gh pr create --title "<title>" --body "<body>" --base main
   

3. Update Linear:

   • Status: In Review
   • Add PR link as comment

4. Monitor CI:

   • Invoke yux-ci-monitor skill
   • Report status to user

4. Merge Completion

When CI passes and reviews approved:

1. Merge PR:

   gh pr merge <number> --squash --delete-branch
   

2. Cleanup:

   git checkout main
   git pull origin main
   git branch -d <branch-name>
   

3. Update Linear:

   • Status: Done
   • Add completion comment

Branch Naming Convention

Format: <type>/LIN-<issue-id>-<short-description>

Type	Use Case
feat	New features
fix	Bug fixes
docs	Documentation
refactor	Code refactoring
test	Test additions
chore	Maintenance

Examples:

• feat/LIN-123-user-auth
• fix/LIN-456-login-bug
• docs/LIN-789-api-docs

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]
Refs: LIN-xxx

Examples:

• feat(auth): add JWT token validation
• fix(ui): correct button alignment
• docs(api): update endpoint documentation

Error Handling

Linear Not Configured

Linear MCP is not configured.

To set up Linear:
1. Run /mcp in Claude Code
2. Add the Linear MCP server
3. Complete OAuth authorization

Not in Git Repository

Not inside a git repository.

Please navigate to your project directory and try again.

Branch Already Exists

Branch <name> already exists.

Options:
1. Switch to existing branch
2. Create branch with different name
3. Delete existing branch and recreate

CI Failed

CI checks failed.

Failed: <check-name>
Error: <error-message>

To fix:
1. Review the error details
2. Make necessary changes
3. Push fixes
4. CI will re-run automatically

Integration Points

Linear MCP Functions

Function	Purpose
searchIssues	Find existing issues
createIssue	Create new issue
getIssue	Get issue details
updateIssue	Update status/fields
createComment	Add progress comments

GitHub CLI (gh)

Command	Purpose
gh auth status	Verify authentication
gh pr create	Create pull request
gh pr view	Get PR details
gh pr checks	Check CI status
gh pr merge	Merge pull request
gh run view	Get CI run details

Output Examples

Output language follows .claude/yux-config.json setting

Task Started

=== Task Started ===

Issue:   LIN-456 - Implement user authentication
Status:  In Progress
Branch:  feat/LIN-456-user-auth

You can now start coding!

Task Completed

=== Task Completed! ===

Issue:   LIN-456 - Implement user authentication
Status:  Done
PR:      #78 merged to main

Great work! Use /yux-linear-start for your next task.