linear-subagent-guide

What this skill does

# Linear Subagent Guide

## ⛔ EXACT LINEAR MCP PARAMETERS (VERIFIED)

**These are the EXACT parameter names from `get_server_tools`. Copy exactly.**

### Most Common Operations

```javascript
// GET ISSUE - uses "id"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "get_issue",
  args: { id: "WORK-26" }  // ✅ CORRECT - "id" not "issueId"
})

// UPDATE ISSUE - uses "id"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "update_issue",
  args: {
    id: "WORK-26",        // ✅ CORRECT - "id" not "issueId"
    description: "...",
    state: "In Progress"
  }
})

// CREATE COMMENT - uses "issueId"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "create_comment",
  args: {
    issueId: "WORK-26",   // ✅ CORRECT - "issueId" for comments
    body: "Comment text"
  }
})

// LIST COMMENTS - uses "issueId"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "list_comments",
  args: { issueId: "WORK-26" }  // ✅ CORRECT
})
```

### Parameter Reference Table

| Tool | Required Parameter | Example Args |
|------|-------------------|--------------|
| `get_issue` | `id` | `{ id: "WORK-26" }` |
| `update_issue` | `id` | `{ id: "WORK-26", ... }` |
| `create_comment` | `issueId`, `body` | `{ issueId: "WORK-26", body: "..." }` |
| `list_comments` | `issueId` | `{ issueId: "WORK-26" }` |
| `create_issue` | `title`, `team` | `{ title: "...", team: "..." }` |
| `get_project` | `query` | `{ query: "ProjectName" }` |
| `get_team` | `query` | `{ query: "TeamName" }` |
| `get_user` | `query` | `{ query: "me" }` |

---

## Overview

The **Linear subagent** (`ccpm:linear-operations`) is a dedicated MCP handler that optimizes all Linear API operations in CCPM. Rather than making direct Linear MCP calls, commands should delegate to this subagent, which provides:

- **50-60% token reduction** (15k-25k → 8k-12k per workflow)
- **Session-level caching** with 85-95% hit rates
- **Performance**: <50ms for cached operations (vs 400-600ms direct)
- **Structured error handling** with actionable suggestions
- **Centralized logic** for Linear operations consistency

## When to Use the Linear Subagent

**Use the subagent for:**
- Reading issues, projects, teams, statuses
- Creating or updating issues, projects
- Managing labels and comments
- Fetching documents and cycles
- Searching Linear documentation

**Never use the subagent for:**
- Local file operations
- Git commands
- External API calls (except Linear)

---

## ⚠️ CRITICAL: Parameter Name Gotcha

**Different Linear MCP tools use different parameter names for issue IDs:**

| Tool | Parameter | WRONG | CORRECT |
|------|-----------|-------|---------|
| `get_issue` | `id` | `{ issueId: "X" }` ❌ | `{ id: "X" }` ✅ |
| `update_issue` | `id` | `{ issueId: "X" }` ❌ | `{ id: "X" }` ✅ |
| `create_comment` | `issueId` | `{ id: "X" }` ❌ | `{ issueId: "X" }` ✅ |
| `list_comments` | `issueId` | `{ id: "X" }` ❌ | `{ issueId: "X" }` ✅ |

**First-call failures** are often caused by using `issueId` instead of `id` for `get_issue`/`update_issue`.

---

## Available Linear MCP Tools (Complete Reference)

Linear MCP provides **23 tools** for interacting with Linear. This is the complete, validated list.

---

### 1. Comments (2 tools)

#### `list_comments`
List comments for a specific Linear issue.

**Parameters:**
- `issueId` (string, required) - The issue ID

**Example:**
```javascript
mcp__linear__list_comments({ issueId: "PSN-41" })
```

#### `create_comment`
Create a comment on a specific Linear issue.

**Parameters:**
- `issueId` (string, required) - The issue ID
- `body` (string, required) - The content of the comment as Markdown
- `parentId` (string, optional) - A parent comment ID to reply to

**Linear's Native Collapsible Syntax:**
Use `+++` to create collapsible sections (starts collapsed, native Linear feature):
```
+++ Section Title
Content here (multi-line markdown supported)
+++
```

**Example (simple):**
```javascript
mcp__linear__create_comment({
  issueId: "PSN-41",
  body: "## Progress Update\n\nCompleted first phase."
})
```

**Example (with collapsible section):**
```javascript
mcp__linear__create_comment({
  issueId: "PSN-41",
  body: `🔄 **Progress Update**

Completed first phase, all tests passing

+++ 📋 Detailed Context
**Changed Files:**
- src/auth.ts
- src/tests/auth.test.ts

**Next Steps:**
- Implement phase 2
- Update documentation
+++`
})
```

---

### 2. Cycles (1 tool)

#### `list_cycles`
Retrieve cycles for a specific Linear team.

**Parameters:**
- `teamId` (string, required) - The team ID
- `type` (string, optional) - "current", "previous", or "next"

**Example:**
```javascript
mcp__linear__list_cycles({ teamId: "team-123", type: "current" })
```

---

### 3. Documents (2 tools)

#### `get_document`
Retrieve a Linear document by ID or slug.

**Parameters:**
- `id` (string, required) - The document ID or slug

**Example:**
```javascript
mcp__linear__get_document({ id: "doc-abc-123" })
```

#### `list_documents`
List documents in the user's Linear workspace.

**Parameters:**
- `limit` (number, optional, max 250, default 50)
- `before` (string, optional) - An ID to end at
- `after` (string, optional) - An ID to start from
- `orderBy` (string, optional) - "createdAt" or "updatedAt" (default: "updatedAt")
- `query` (string, optional) - Search query
- `projectId` (string, optional) - Filter by project ID
- `initiativeId` (string, optional) - Filter by initiative ID
- `creatorId` (string, optional) - Filter by creator ID
- `createdAt` (string, optional) - ISO-8601 date-time or duration (e.g., "-P1D")
- `updatedAt` (string, optional) - ISO-8601 date-time or duration
- `includeArchived` (boolean, optional, default false)

**Example:**
```javascript
mcp__linear__list_documents({ projectId: "proj-123", limit: 20 })
```

---

### 4. Issues (4 tools)

#### `get_issue`
Retrieve detailed information about an issue by ID.

**Parameters:**
- `id` (string, required) - The issue ID (e.g., "PSN-41")

**Example:**
```javascript
mcp__linear__get_issue({ id: "PSN-41" })
```

#### `list_issues`
List issues in the user's Linear workspace. Use "me" for assignee to get your issues.

**Parameters:**
- `limit` (number, optional, max 250, default 50)
- `before` (string, optional)
- `after` (string, optional)
- `orderBy` (string, optional) - "createdAt" or "updatedAt"
- `query` (string, optional) - Search title or description
- `team` (string, optional) - Team name or ID
- `state` (string, optional) - State name or ID
- `cycle` (string, optional) - Cycle name or ID
- `label` (string, optional) - Label name or ID
- `assignee` (string, optional) - User ID, name, email, or "me"
- `delegate` (string, optional) - Agent name or ID
- `project` (string, optional) - Project name or ID
- `parentId` (string, optional) - Parent issue ID
- `createdAt` (string, optional) - ISO-8601 date-time or duration
- `updatedAt` (string, optional) - ISO-8601 date-time or duration
- `includeArchived` (boolean, optional, default true)

**Example:**
```javascript
mcp__linear__list_issues({ assignee: "me", state: "In Progress" })
```

#### `create_issue`
Create a new Linear issue.

**Parameters:**
- `title` (string, required)
- `team` (string, required) - Team name or ID
- `description` (string, optional) - Markdown description
- `cycle` (string, optional) - Cycle name, number, or ID
- `priority` (number, optional) - 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low
- `project` (string, optional) - Project name or ID
- `state` (string, optional) - State type, name, or ID
- `assignee` (string, optional) - User ID, name, email, or "me"
- `delegate` (string, optional) - Agent name, displayName, or ID
- `labels` (array of strings, optional) - Label names or IDs
- `dueDate` (string, optional) - ISO format date
- `parentId` (string, optional) - Parent issue ID for sub-issues
- `links` (array of objects, optional) - Each object needs `url` and `title`

**Example:**
```javascript
mcp__linear__create_issue({
  title: "Fix au