Linear project management: MCP/GraphQL API, VantageEx epic authoring, auditing, and grooming

version
0.1.10
GitHub stars
27

Install

/plugin install linear@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 1

Linear

Manage Linear issues, author VantageEx-compatible epics, and interact with the Linear API via MCP or direct GraphQL.

MCP Setup (Preferred)

The Linear MCP server provides tool-based access to Linear. Set up once:

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Then run /mcp in a Claude Code session to complete OAuth authentication (opens browser).

After setup, use MCP tools directly for all Linear operations. The MCP server handles authentication and provides structured tool interfaces.

For full setup details, troubleshooting, and alternative client configurations, read references/mcp-setup.md.

GraphQL Fallback

When MCP is unavailable (headless environments, scripting, CI), use the GraphQL API directly.

Endpoint: https://api.linear.app/graphql Auth: Bearer token via LINEAR_API_KEY environment variable

# Test connectivity
curl -s -H "Authorization: Bearer $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' \
  https://api.linear.app/graphql

For the full query catalog, read references/graphql-api.md.

The nushell client at scripts/0.1.0/linear.nu wraps common GraphQL operations.

Common Operations

Query an Issue

By key (e.g., MT-686):

query IssueByKey($key: String!) {
  issue(id: $key) {
    id identifier title url description
    state { id name type }
    project { id name }
    labels { nodes { name } }
    attachments { nodes { title url sourceType } }
  }
}

Create an Issue

mutation CreateIssue($teamId: String!, $title: String!, $description: String, $stateId: String, $labelIds: [String!]) {
  issueCreate(input: {
    teamId: $teamId
    title: $title
    description: $description
    stateId: $stateId
    labelIds: $labelIds
  }) {
    success
    issue { id identifier url }
  }
}

Update Issue State

Always fetch team workflow states first to get the exact stateId:

query IssueTeamStates($id: String!) {
  issue(id: $id) {
    team {
      states { nodes { id name type } }
    }
  }
}

Then transition:

mutation MoveIssue($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue { id identifier state { name } }
  }
}

Add a Comment

mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment { id url }
  }
}

Attach a GitHub PR

Prefer the GitHub-specific mutation for PR metadata:

mutation AttachPR($issueId: String!, $url: String!, $title: String) {
  attachmentLinkGitHubPR(issueId: $issueId, url: $url, title: $title, linkKind: links) {
    success
    attachment { id title url }
  }
}

List Workflow States

query TeamStates($teamId: String!) {
  team(id: $teamId) {
    states { nodes { id name type position } }
  }
}

Introspection

When an unfamiliar mutation or type is needed, query the schema:

query ListMutations {
  __type(name: "Mutation") { fields { name } }
}

query InspectInput($typeName: String!) {
  __type(name: $typeName) {
    inputFields { name type { kind name ofType { kind name } } }
  }
}

VantageEx Epic Format

VantageEx epics follow a three-level hierarchy: Epic (user-authored) -> Issues (team leader creates) -> Tasks (agents create).

The user authors the epic description in Linear. The epic body uses markdown sections that VantageEx parses.

Required Sections

SectionPurposeAuthor
## Objective2-3 sentences defining success criteriaUser (immutable)
## SkillsDomain-specific skills needed (core skills implicit)User (immutable)
## ReposTarget repositoriesUser (immutable)

Optional Sections

SectionPurposeAuthor
## InstructionsUser guidance added at re-queue (ADR-027)User or dashboard
## ConstraintsBoundaries (defaults: mise run ci, no attribution, squash merge)User
## AgentsPriority-ordered agent CLIs from {claude, codex, antigravity, local} (default [claude])User
## TeamClaude model layer: lead, default, escalation (applies when Agents resolves to claude)User
## EscalationFailure and ambiguity policiesUser
## PRPull request URL when submittedAgent

Title and Slug

  • Title: Imperative statement ("Implement OAuth2 PKCE flow for API gateway")
  • Slug: kebab-case, max ~30 chars, URL-safe (oauth-pkce-flow)
  • Branch: feature/<epic-slug>

For the full epic specification with examples and anti-patterns, read references/epic-format.md.

Epic Body Format Rules

Epic bodies use plain markdown for every section. Parsers that ingest epic bodies (including the /linear:audit-epics command and downstream consumers) capture YAML fences as garbage labels.

No YAML fences in epic bodies

WRONG:

## Skills

```yaml
- skill1
- skill2
```

CORRECT:

## Skills

- skill1
- skill2

Skills, Repos, and Constraints sections all use plain bullet lists. Code fences in these sections produce empty or junk labels in the parser output.

Skill-label discipline

Skill labels listed in the epic body must exist in the claude-skills marketplace at https://github.com/vinnie357/claude-skills/blob/main/.claude-plugin/marketplace.json. The audit command checks this; missing labels are flagged.

Core skills are implicit and MUST NOT be listed in epic bodies: anti-fabrication, git, tdd, twelve-factor, security, mise, nushell. Listing them adds noise without value — every epic loads them by default.

Self-contained content

Epic bodies are self-contained. Workers pick up epics on any machine; local-filesystem paths (~/.claude/plans/..., /Users/<name>/...) resolve only on the author's system and fail everywhere else.

WRONG — points at a local file:

See `~/.claude/plans/foo.md` for the design context.

CORRECT — embed the content inline under a ## Design context (or similarly named) section, or link to another epic by URL:

## Design context

[full design content pasted here]
## Instructions

Design rationale lives in the paired docs epic [VIN-316](https://linear.app/...).

When a design plan is too large for a single body, split into paired epics (docs + implementation) linked by URL. Each epic carries its own self-contained context; cross-references between epics use URLs, never filesystem paths.

Initial state

New epics start in Backlog. Labels are team-scoped; missing skill labels auto-create on first use via issueLabelCreate.

Workflow States

Linear uses typed workflow states. VantageEx maps these to its lifecycle:

VantageEx StatusLinear StateMeaning
readyBacklog / ReadyEpic in backlog, all fields present
up_nextUp NextUser approved for agent work
in_progressIn ProgressAgent actively working
needs_helpNeeds HelpAgent exhausted fix cycles
reviewIn ReviewCI passed, PR created
completeDonePR merged
archivedArchivedHidden from dashboard

Key transitions:

  • ready -> up_next: User only (the gate)
  • up_next -> in_progress: EpicPickerWorker (automatic)
  • in_progress -> needs_help: ValidateWorker (after 3 fix cycles)
  • needs_help -> up_next: User re-queues with ## Instructions
  • in_progress -> review: Agent submits PR
  • review -> complete: User merges PR

For the full state machine and cross-system mapping, read references/workflow-states.md.

Commands

CommandPurpose
/linear:plan-epicCreate a new VantageEx-compatible epic in Linear
/linear:audit-epicsAudit existing epics for VantageEx compatibility
/linear:groom-epicsFix issues found by audit

References

FileContent
references/mcp-setup.mdLinear MCP server setup and troubleshooting
references/graphql-api.mdFull GraphQL query catalog
references/epic-format.mdVantageEx epic specification
references/audit-checklist.mdEpic validation checks
references/epic-sizing.mdEpic sizing heuristics and dependency-ordering conventions
references/workflow-states.mdState machine and cross-system mapping

Templates

FileContent
templates/0.1.0/epic.mdEpic description template
templates/0.1.0/audit-report.mdAudit output format
templates/0.1.0/team-definition.mdTeam section template

Scripts

FileContent
scripts/0.1.0/linear.nuNushell GraphQL client for non-MCP use

Usage Rules

  • Prefer MCP tools over raw GraphQL when the Linear MCP server is configured
  • For state transitions, always fetch team states first — never hardcode stateId values
  • Prefer attachmentLinkGitHubPR over attachmentLinkURL when linking GitHub PRs
  • Keep queries narrow — request only the fields needed
  • Treat top-level errors array in GraphQL responses as failures
  • When writing epic descriptions, follow the section format exactly — VantageEx parses these programmatically

Commands 3

Audit existing Linear epics for VantageEx compatibility.

Steps

  1. Load the /linear skill
  2. Read the audit checklist at references/audit-checklist.md
  3. Read the audit report template at templates/0.1.0/audit-report.md

Fetch Issues

Determine scope from arguments:

  • --issue=<key>: Audit a single issue by key (e.g., MT-123)
  • --project=<slug>: Audit all issues in a project
  • --state=<state>: Filter by Linear state type (e.g., "started", "unstarted", "completed")
  • No arguments: Ask the user which project or issues to audit

Use Linear MCP tools (preferred) or GraphQL to fetch issues with their full descriptions, states, labels, and attachments.

Run Checks

For each issue, run every check from the audit checklist:

Structure Checks

  • Parse description for ## Objective, ## Skills, ## Repos sections
  • Validate objective quality (2-3 sentences)
  • Validate skills exist in marketplace (read marketplace.json)
  • Check for core skills that should not be listed

Team Checks

  • Check for ## Team section
  • Check for escalation policy

Naming Checks

  • Evaluate title quality (imperative statement)
  • Check slug derivability
  • Check branch naming convention if branch exists

State Consistency Checks

  • For completed/review issues: check for ## PR section or GitHub PR attachment
  • For needs_help issues: check for blocker documentation
  • Use gh pr list and gh pr view to cross-reference PR URLs

Epic-Sizing Checks

See references/epic-sizing.md for thresholds.

  • Flag epics with > 8 issues — signal to split the epic
  • Flag issues with > ~10 target files — exceeds one worker session
  • Flag multi-deliverable issue titles (joined by "and", "also", "then", "plus") — split them
  • Flag acceptance criteria that cannot be verified in a single worker session
  • Flag issues with cross-subsystem or cross-repo scope — split candidates

Dependency-Ordering Checks

See references/epic-sizing.md for conventions.

  • Flag issues with implicit or missing dependency declarations (no blocking relations / bees deps)
  • Flag dependency cycles — halt: re-decompose required before queueing
  • Flag dependency chains deeper than 5 levels — serializes workers unnecessarily
  • Flag independent issues that are serialized without cause — reduces worker fan-out
  • Flag a DAG source issue that is itself marked blockedBy another issue — inconsistent foundational ordering

Generate Report

Use the templates/0.1.0/audit-report.md format:

  1. Summary table with counts by severity
  2. Per-issue findings sorted by error count (most errors first)
  3. Each finding includes: check name, severity, status, detail
  4. Remediation actions for each failing check

Output

Present the report to the user. Suggest running /linear:groom-epics to fix errors and warnings automatically.

Fix VantageEx compatibility issues across one epic or a whole project. Scoped, pre-flight-gated, and offloads the audit pass to a haiku mapper so the parent session never holds full descriptions for an entire project.

Steps

  1. Load the /linear skill
  2. Read the epic format spec at references/epic-format.md
  3. Read the audit checklist at references/audit-checklist.md
  4. Read the team definition template at templates/0.1.0/team-definition.md

Phase A — Pre-flight

Run on every invocation. Halt with a clear message if any check fails — never partial-progress.

  1. Verify Linear access. Pass if either:

    • The Linear MCP server is registered (claude mcp list shows a linear-server entry), OR
    • LINEAR_API_KEY environment variable is set.

    If neither, halt with:

    Linear access is not configured. Set up one of:

  2. Resolve scope from arguments:

    • --issue=<key> (e.g., --issue=VIN-42) → single-issue path. Skip Phase B; audit + groom inline.
    • --project=<slug> → project path. Continue to Phase B.
    • Neither → ask the user which scope.
  3. For project scope: identify open-state IDs. Query the team's workflowStates and keep only states whose type is in {triage, backlog, unstarted, started}. Exclude any state whose type is completed or canceled — grooming closed epics is forbidden and would mutate finished work.

  4. Count candidates. Query the project for issues in the open-state IDs only. Print the count.

  5. Overload gate. If count >= --max-issues (default 50), refuse to proceed without --confirm-bulk. Suggest narrowing with --issue=<key> or batching as a follow-up. This is a hard gate — --auto does not bypass it.

Phase B — Mapper (project scope only)

Spawn a single read-only haiku agent to audit all candidates and return a compact digest. The parent session never holds the full descriptions.

Use the Task tool with subagent_type: Explore and model: haiku. The mapper prompt:

## Load skills

Load these by exact name (no globs):
- /linear (provides MCP/GraphQL helpers and the epic format spec)
- /core:anti-fabrication (no claim without tool verification)

Quote one sentence from each loaded skill in your first response.

## Task

You are auditing Linear epics for VantageEx compatibility. READ-ONLY — do not write to Linear.

For each issue in the candidate list, fetch via Linear MCP (preferred) or GraphQL:
  - identifier, url, title, state.name, state.type, labels, attachments
  - full description

Run the structure + content checks from `references/audit-checklist.md`:
  - Objective Present, Objective Quality
  - Skills Present, Skills Valid, Skills Not Listing Core
  - Repos Present
  - Agents Valid, Agents Section Non-Empty
  - Team Defined
  - PR on Completed (only for state.type == "started" with a state.name suggesting review)
  - Implementation Details

Return JSON, sorted by error_count desc, truncated to top 25:

[
  {
    "identifier": "VIN-42",
    "url": "https://linear.app/...",
    "state_type": "started",
    "state_name": "In Progress",
    "error_count": 2,
    "warning_count": 1,
    "info_count": 0,
    "findings": [
      {"check": "Objective Present", "severity": "error"},
      {"check": "Agents Valid", "severity": "warning", "detail": "gemini -> antigravity"}
    ]
  }
]

Do not include description bodies in the response. The groom phase re-fetches them.

Phase C — Groom

For single-issue scope: audit the one issue inline, then proceed to fix. For project scope: iterate over the mapper digest.

For each entry:

  1. Re-fetch the full issue body via MCP or GraphQL (only at fix time — Phase B kept tokens cheap).

  2. Apply fixes per check:

Missing Objective

  • If the title is descriptive, generate a 2-3 sentence objective from the title and any existing content
  • Ask the user to confirm before applying
  • --auto skips this fix (content change requires human review)

Missing Skills

  • Suggest skills from the title and description
  • Validate against marketplace.json
  • Ask the user to confirm the skill list

Missing Repos

  • Check the description and comments for repo names
  • Ask the user to specify if none can be inferred

Missing Team

  • Insert the default team definition: lead: sonnet, default_model: haiku, escalation: haiku -> sonnet -> opus
  • Apply without asking (safe default)

Core Skills Listed

  • Strip core skills (anti-fabrication, git, tdd, twelve-factor, security, mise, nushell) automatically

Invalid Agents

  • Confirm with the user before any rewrite
  • Rewrite gemini → antigravity (the Google CLI runs Gemini)
  • Flag any other unknown value (e.g., gpt4, bard) — do not auto-rewrite

Empty Agents Section

  • Ask the user: remove the empty header (default [claude] applies) or fill in agents
  • No auto-fix — intent is ambiguous

Missing PR on Completed

  • Search via gh pr list --search "<issue-identifier>" and gh pr list --search "<title>"
  • If found, attach via attachmentLinkGitHubPR and add ## PR section
  • If no PR found, flag for manual resolution
  • (Phase A excludes completed/canceled epics; this rule fires only for review-state work)

Implementation Details in Description

  • Flag the specific content for user review
  • Do not auto-remove — user may have intentional content
  1. Apply writes via Linear MCP (preferred) or GraphQL.

--auto semantics: safe fixes (team default insertion, core-skill stripping) apply silently. Content fixes (objective, skills, repos, invalid agents) still confirm with the user.

Phase D — Verify + Report

  1. Re-run the audit checks on touched epics (reuse the same check set from Phase B).
  2. Output a summary:
    • Before/after error + warning counts per epic
    • Epics flagged but skipped (user declined a content fix)
    • Any writes that failed (auth, mutation errors) — these get listed individually with error text
  3. For project scope, also report the top-25 cap — if more epics had findings, name the next batch the user can target.

Auto Mode

If --auto is specified:

  • Apply all safe fixes without asking (team defaults, core skill removal)
  • Still ask for confirmation on content changes (objective, skills, repos, invalid agents)
  • Empty Agents Section still requires user input (no auto-fix)
  • Pre-flight overload gate still applies (--auto does not bypass --confirm-bulk)

Create a new VantageEx-compatible epic in Linear.

Steps

  1. Load the /linear skill
  2. Read the epic template at templates/0.1.0/epic.md
  3. Read the epic format spec at references/epic-format.md

Gather Information

Interactively collect from the user:

  • Title: Clear, imperative statement of what gets built
  • Slug: Derive from title (kebab-case, max ~30 chars). Confirm with user.
  • Objective: 2-3 sentences defining success criteria
  • Skills: Domain-specific skills needed. Validate each against the marketplace at https://github.com/vinnie357/claude-skills/blob/main/.claude-plugin/marketplace.json. Warn if a skill is not found.
  • Repos: Target repositories
  • Constraints: Optional. Note that defaults apply (mise run ci, no attribution, squash merge, feature/)
  • Team: Optional. Default: lead=sonnet, default_model=haiku, escalation=haiku->sonnet->opus

Size & Order

Apply references/epic-sizing.md to the issues you intend to create:

  • Decompose the epic into 3–8 independently completable issues. If the count would exceed 8, split the epic.
  • Size each issue to one worker session: ≤ ~10 target files, one deliverable, one subsystem, verifiable by a single acceptance check. Reject multi-deliverable titles (joined by "and/also/then/plus") — split them.
  • Declare dependencies explicitly using Linear blocking relations. Never rely on implicit ordering.
  • Order topologically: foundation issues (schemas, references, interfaces) first, then core, integration, and verification. No cycles — if a cycle is detected, re-decompose before proceeding.
  • Keep chains shallow: dependency depth < 5 levels; do not serialize issues that can run in parallel.

See references/epic-sizing.md for thresholds and the full checklist.

Validate

Before creating:

  • Confirm skills exist in the marketplace (read marketplace.json from the claude-skills repo)
  • Confirm core skills are NOT listed (anti-fabrication, git, tdd, twelve-factor, security, mise, nushell)
  • Confirm objective is 2-3 sentences
  • Confirm slug is kebab-case and under 30 chars
  • Confirm at least one repo is specified
  • Confirm the body is self-contained: no local-filesystem paths (~/.claude/..., /Users/<name>/...) used as the source of truth. Embed design plans inline under a ## Design context section, or link to other epics by Linear URL.
  • Sizing check: confirm the objective's scope can decompose into approximately 6–8 independently-shippable issues (the adopted sizing convention; see "Epic Sizing Heuristics" in references/epic-format.md). If the scope appears to require significantly more issues, spans many repositories with large cross-cutting changes, or contains work that could be separately delivered, prompt the user to consider splitting into multiple epics.
  • Dependency-ordering check: confirm that the anticipated issues can be ordered topologically (foundational work first, no cycles). If the user has described ordering intent, include a ## Dependencies section in the epic body; see "Dependency Ordering" in references/epic-format.md for format and rules.

Body Format Rules

Apply the format rules from the /linear skill's "Epic Body Format Rules" section to the body you produce in the next step:

  • Plain markdown only — no YAML fences in any section.
  • Skill labels must exist in the marketplace; core skills (anti-fabrication, git, tdd, twelve-factor, security, mise, nushell) are implicit and not listed.
  • Initial state is Backlog.
  • Bodies are self-contained: embed design context inline, cross-link other epics by Linear URL, never reference local-filesystem paths.

See plugins/tools/linear/skills/linear/SKILL.md "Epic Body Format Rules" for the canonical wording.

When the epic's anticipated issue ordering is known, include a ## Dependencies section in the produced body declaring which issues depend on which others, with foundational issues listed first. The team leader translates this into formal blockedBy edges in Linear during decomposition. See "Dependency Ordering" in references/epic-format.md for format and rules.

Create in Linear

Use the Linear MCP tools (preferred) or the GraphQL API to:

  1. Create the issue with the title
  2. Set the description using the template format with all gathered sections
  3. Apply skill names as labels (create labels if they do not exist)
  4. Set initial state to "Ready" or "Backlog" (the default unstarted state)

Report

Output:

  • Linear issue URL
  • Issue identifier (e.g., MT-123)
  • Feature branch name: feature/<slug>
  • Summary of what was created

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/linear
Category
Tools
License
MIT
Keywords
linear, project-management, epics, graphql, vantageex, mcp

More from vinnie357/claude-skills

All 33