How does provider detection work?

Provider detection relies on URL patterns (e.g., Linear or Jira links) or the issue ID pattern like CIR-123. If the match is ambiguous, the system will ask you to clarify.

What if the MCP for a provider isn't configured?

You will be prompted that the provider MCP is not configured and given steps to enable issue tracking (install the plugin and authenticate). Would you like to continue without issue tracking?

What commands are available and what do they do?

/issue-work starts work on an issue and moves it to In Progress; /issue-update adds progress notes or blockers; /issue-done completes the work and moves the issue to Done.

issue-workflow

npx machina-cli add skill thomasindrias/issue-dev/issue-workflow --openclaw

Files (1)

SKILL.md

3.5 KB

Issue Workflow Management

This skill guides you through managing issue/ticket states during development work across multiple project management providers.

RFC2119 Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Supported Providers

Provider	URL Pattern	MCP Required
Linear	`https://linear.app//issue/`	`linear@claude-plugins-official`
JIRA	`https://.atlassian.net/browse/`	JIRA MCP (Atlassian)

State Transition Requirements

Start of work: You MUST move the issue to "In Progress" (or equivalent started state)
During work: You SHOULD add comments for significant progress or blockers
Completion: You MUST move the issue to "Done" (or equivalent completed state) with completion notes

When to Update Issues

You MUST update issues:

When starting work on an issue
When completing work

You SHOULD update issues:

When encountering blockers or changing approach
When acceptance criteria change

Provider Detection

You MUST automatically detect providers from these formats:

URL-Based (Highest Priority)

Linear: https://linear.app/*/issue/*
JIRA: https://*.atlassian.net/browse/* or https://*.jira.com/browse/*

Issue ID Pattern

Pattern: [A-Z]{2,10}-\d+ (e.g., CIR-123, PROJ-456)
This pattern MAY match multiple providers
If ambiguous, check context or ask user

MCP Availability

Before performing any operation, you MUST verify the required MCP is available.

If MCP is NOT available:

The [Provider] MCP is not configured. To enable issue tracking:
1. Install the plugin: `claude plugin install [provider]@claude-plugins-official`
2. Authenticate when prompted

Would you like to continue without issue tracking?

You MUST NOT attempt to call unavailable MCP tools.

Provider-Specific Tool Reference

Linear MCP Tools

// Get issue
mcp__plugin_linear_linear__get_issue({ "id": "CIR-123" })

// List team statuses
mcp__plugin_linear_linear__list_issue_statuses({ "team": "team-id" })

// Update issue
mcp__plugin_linear_linear__update_issue({ "id": "uuid", "state": "In Progress" })

// Add comment
mcp__plugin_linear_linear__create_comment({ "issueId": "uuid", "body": "Comment" })

JIRA MCP Tools

// Get issue
mcp__atlassian_jira__get_issue({ "issueKey": "PROJ-456" })

// Get transitions
mcp__atlassian_jira__get_transitions({ "issueKey": "PROJ-456" })

// Transition issue
mcp__atlassian_jira__transition_issue({ "issueKey": "PROJ-456", "transitionId": "21" })

// Add comment
mcp__atlassian_jira__add_comment({ "issueKey": "PROJ-456", "body": "Comment" })

Workflow Commands

/issue-work [issue-id-or-url] - Start working on an issue (moves to In Progress)
/issue-update [comment] - Add progress update or modify issue
/issue-done [comment] - Complete work (moves to Done)

Session Context

You MUST track within the conversation:

The active issue ID
The provider being used

Output format: Active issue: [ID] ([Provider])

This enables subsequent commands without re-specifying the issue or provider.

Source

git clone https://github.com/thomasindrias/issue-dev/blob/main/.claude-plugin/skills/issue-workflow/SKILL.mdView on GitHub

Overview

This skill guides you through managing issue and ticket states during development across multiple project-management providers such as Linear and JIRA. It covers initiating work, logging progress with comments, and completing tickets with proper state transitions to keep your boards in sync. It's designed to help teams maintain consistent workflow discipline across tools.

How This Skill Works

It automatically detects the active provider from URL patterns or issue IDs, and verifies that the required MCP is available before acting. It then uses provider-specific tools to move issue states (e.g., In Progress, Done) and to add comments for updates or blockers. You can trigger these actions with the built-in commands: /issue-work, /issue-update, and /issue-done.

When to Use It

Starting work on an issue to move it to In Progress
Recording progress or blockers with meaningful comments
Updating acceptance criteria or approach when plans change
Completing work and moving the issue to Done with notes
Working across Linear and JIRA from the same session

Quick Start

Step 1: Identify the active issue and its provider (via URL or issue ID).
Step 2: Run /issue-work [issue-id-or-url] to move the issue to In Progress.
Step 3: Use /issue-update to log progress and /issue-done when you finish, adding a completion note.

Best Practices

Always move the issue to In Progress at the start of work
Add concise, actionable comments for blockers and progress
Move to Done with a clear completion note
Verify the correct provider (MCP) is configured before acting
Keep the Active issue and Provider in session context for seamless commands

Example Use Cases

Start Linear CIR-123 to In Progress using /issue-work CIR-123
Add a blocker comment to CIR-123 as you investigate
Transition JIRA PROJ-456 to Done with final notes
Update acceptance criteria for PROJ-789 and reflect changes on the issue
Switch provider context mid-session when needed and continue updates

Frequently Asked Questions

Add this skill to your agents