---

name: yux-linear-workflow description: Complete Linear workflow automation for development tasks. Triggers: "linear workflow", "start task", "work on issue", "create pr", "merge pr", "开始任务", "处理Issue", "创建PR", "合并PR". allowed-tools: Read, Write, Glob, Grep, Bash(git:), Bash(gh:), mcp__linear__*

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

Copy{
  "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

Core Functions

1. Start Task

When user wants to start a new task:

1. MANDATORY: Verify Linear connection:

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

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

   Copymcp__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

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

6. Update Linear status:

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

7. Save local state file:

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

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

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:

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

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

2. Cleanup:

   Copygit 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>

Examples:

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

Commit Message Format

Follow Conventional Commits:

Copy<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

CopyLinear 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

CopyNot inside a git repository.

Please navigate to your project directory and try again.

Branch Already Exists

CopyBranch <name> already exists.

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

CI Failed

CopyCI 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

GitHub CLI (gh)

Output Examples

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

Task Started

Copy=== Task Started ===

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

You can now start coding!

Task Completed

Copy=== 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.