linear-pm — claude-skills

01 Overview

linear-pm is a Claude Code plugin that makes Linear the operational center for autonomous development. Six slash commands let you file issues with structured templates (Why/What/Acceptance criteria), have Claude pick them up and either propose a plan (review-only mode) or write code, run verifications, open PRs, and keep Linear status in sync. Built-in label taxonomy (agent-ready, agent-blocked, needs-spec) and three autonomy modes (disabled, review-only, allowed) let teams start conservative — reviewing proposed plans first — then graduate to full autonomous implementation as trust builds. Every action is logged as a Linear comment for visibility.

02 Problem & why it's needed

The friction

Project teams split attention between Linear (issue tracking), GitHub (code), and conversations — status falls out of sync, branches aren't linked to issues, autonomous agents can't safely pick work. Without tight integration, Linear becomes a write-once tool and real truth lives in Slack.

Why it mattersTeams want Linear to be the single source of truth for "what to build next." They need Claude to pick up agent-ready issues, implement them in isolated branches with safety gates, run verify commands, open PRs, and keep Linear synchronized — all automatically, with human control over autonomy level per repo.

03 Install

Install via Claude Code plugin marketplace

/plugin marketplace add abhijitbansal/claude-skills

/plugin install linear-pm@claude-skills

Bootstrap this repo (one time)

./.claude/skills/linear-pm/scripts/bootstrap.sh

Checks prerequisites (git, gh CLI, Linear MCP), validates .claude/linear.yml, and prints setup instructions. Idempotent — rerun anytime to diagnose drift.

Initialize Linear PM for the repo

/linear-init

Interactive setup: pick your Linear team and project, creates .claude/linear.yml, and ensures standard labels exist in Linear (agent-ready, agent-blocked, needs-spec, bug, feature, chore, docs).

04 Usability guide

Every capability, how to invoke it, and a concrete example.

/linear-init — Bootstrap (once per repo)

Interactively configure linear-pm for the current repo. Prompts for Linear team and project, generates .claude/linear.yml with sensible defaults (autonomy: review-only, no verify commands), and creates the standard label vocabulary in Linear if missing. Safe to re-run — validates existing config and skips redundant label creation.

/linear-init

/linear-new — File a new issue

Create a Linear issue with the structured template (Why / What / Acceptance criteria / Notes). Can auto-fill context from your recent conversation (file paths, errors, stack traces) into the Notes section. Requires you to supply title, type (bug/feature/chore/docs), one-sentence motivation, concrete description, and at least one acceptance criterion (checkbox). Applies your configured default_labels in addition to the type label.

/linear-new "Add dark-mode toggle to settings" Or without title (interactive): /linear-new

/linear-pick — Autonomous issue pickup

Pick up an agent-ready issue and either propose a plan (review-only mode) or write the code, run verify commands, and open a PR (allowed mode). Can pick the highest-priority agent-ready issue automatically, or jump to a specific issue by key. Refuses work if Acceptance criteria are missing (posts needs-spec label + comment, then stops). Validates the working tree is clean, creates a branch, posts a started comment, implements changes, runs verify commands, pushes, and opens a PR — all with Linear status sync and detailed logging.

/linear-pick Or pick a specific issue: /linear-pick ABH-123

/linear-status — Check what's in flight

Digest of your configured Linear project grouped by status: In Progress (with PR links if open), In Review (with PR links), Blocked (with last blocker comment), Ready queue (agent-ready issues by priority), and recently shipped (Done in last 7 days). Pure read-only — no writes to Linear or git. Helps you context-switch back quickly and spot blockers.

/linear-status

/linear-sync — Backfill Linear state

Reconcile current branch and open PR (if any) with their Linear issue. Parses the issue key from the branch name (e.g., agent/ABH-123-dark-mode or my-fix-ABH-123), posts a comment linking the branch or PR, moves status to In Progress (no PR) or In Review (PR open), and removes agent-ready label. Use when you started work manually outside /linear-pick and want Linear to catch up.

git checkout -b my-feature-ABH-123

# ... do work, push, open PR ...

/linear-sync

/linear-block — Mark blocked with reason

Manually flag an issue as blocked so /linear-pick won't touch it. Adds agent-blocked label and posts a Linear comment with the blocker reason. Can take explicit issue key + reason, or infer from recent context (e.g., you just ran /linear-pick and hit a wall). To unblock: remove agent-blocked in Linear, re-add agent-ready, then re-run /linear-pick.

/linear-block ABH-123 "Waiting for design clarification on button placement" Or just reason (infers issue from context): /linear-block "Need to fix flaky test before proceeding"

Workflow: File and review before autonomous code

Most conservative flow. File an issue with /linear-new, mark it agent-ready in Linear UI (human gate), run /linear-pick in review-only mode (default). You get a 5–15 line plan as a Linear comment. Read it, refine if needed, then flip .claude/linear.yml to autonomy: allowed and re-run /linear-pick to execute.

1. /linear-new "Add export to CSV" 2. (mark agent-ready in Linear UI) 3. /linear-pick → plan posted as Linear comment 4. (review plan, edit .claude/linear.yml to autonomy: allowed) 5. /linear-pick → branch created, code written, PR opened

Workflow: Parallel work with git worktrees

For two simultaneous /linear-pick sessions from the same checkout, use git worktrees to avoid branch collisions. Create a worktree for each issue, start a fresh Claude session in each, then run /linear-pick independently — one can be in review-only while another is allowed. When merged, clean up with git worktree remove.

git worktree add ../doc-scan-ABH-123 -b agent/ABH-123-dark-mode

cd ../doc-scan-ABH-123

claude --remote-control "ABH-123 dark mode"

/linear-pick ABH-123

05 How it works under the hood

Label Taxonomy — Gates Autonomous Work

Every Linear issue gets a type label (bug, feature, chore, docs) and optional control labels. agent-ready signals to /linear-pick that an issue is approved for work; agent-blocked prevents pickup and shows why. needs-spec is applied by /linear-pick when an issue lacks Acceptance criteria (the spec contract). All labels are created once by /linear-init and applied per issue via commands — never auto-created at runtime.

Status Workflow — Tracks Progress

Uses Linear's built-in workflow (no custom states needed). Backlog/Todo → agent picks up → In Progress (branch created) → In Review (PR open) → Done (PR merged by human). /linear-pick moves status automatically; humans trigger Done by merging the PR in GitHub. /linear-status groups issues by status for quick scanning.

Branch Naming — Links to Issues

All branches follow the pattern agent/ISSUE-KEY-slug (e.g., agent/ABH-123-dark-mode). The prefix is configurable in .claude/linear.yml (default agent/). When /linear-sync is run on any branch containing the issue key anywhere, it parses the key out and links back to the issue. This decouples key parsing from strict naming — you can use abhi/ABH-123-fix or agent/ABH-123, both work.

PR Conventions — Auto-Attachment

PR title is derived from the template in .claude/linear.yml (default: {key}: {title} → ABH-123: dark-mode toggle). PR body includes Fixes ABH-123 on a separate line so GitHub's automation auto-closes the issue and links the PR when merged. One PR = one Linear issue; multi-issue PRs aren't supported.

Autonomy Modes — Progressive Trust

Three modes control what /linear-pick does. disabled: read-only, only /linear-new and /linear-sync work. review-only: writes to Linear (status, comments), generates plans, but never writes code or pushes. allowed: full loop — branches, commits, PR. Set per repo in .claude/linear.yml; defaults to review-only to err on the side of safety. Users flip it to allowed once they trust the workflow.

Verify Commands — Safety Gate

Before opening a PR, /linear-pick runs each shell command in the verify: [] list (e.g., ./build.sh, npm test). Non-zero exit = agent-blocked with the failing command + last ~30 lines of output as the reason. Also checks that diff size (added + deleted lines) doesn't exceed max_pr_lines (default 500); oversized diffs auto-block to encourage smaller, reviewable changes.

Config File — Per-Repo Policy

Every repo has .claude/linear.yml (gitignored: no, it's committed). Required keys: team (Linear team key, e.g., ABH), project (project name or ID). Optional: branch_prefix, pr_title_format, autonomy, verify, max_pr_lines, default_labels, poll settings. All values are validated at runtime; missing required keys cause clear errors suggesting /linear-init.

Agent Comments — Transparent Logging

Every action /linear-pick takes is logged to Linear as a comment prefixed with 🤖 emoji: Started — branch name, PR opened — URL, Blocked — reason, Needs spec — what's missing, Plan (review-only) — the proposed plan. Users can see the full history in Linear without querying Claude's session logs.

Session Rename Suggestions — Contextual Session Titles

After /linear-new or /linear-pick touch an issue, the commands emit a copy-pasteable /rename suggestion at the end, gathering all team-prefixed issue keys touched in the current session. Users can paste it to label their Claude Code session (e.g., /rename ABH-123, ABH-124) for easy identification in the session list. Optional but encouraged.

Bootstrap & Validation — Defensive Setup

The bootstrap script checks eight prerequisites in one pass: git installed, inside a git repo, gh CLI installed, gh authenticated, .claude/linear.yml exists, required config keys present, helper scripts (load-config.sh, make-slug.sh, parse-issue-key.sh) present, and informs about Linear MCP (configured in Claude Code, not shell). Idempotent — rerun anytime to diagnose drift. Prints exact fix commands for each gap.

Polling Agent (Optional) — Scheduled Pickup

When poll.enabled: true in .claude/linear.yml, an external polling agent wakes on interval_minutes and runs /linear-pick automatically. Respects all autonomy settings. Useful for continuous delivery workflows where teams want background workers to pick up issues without manual triggers. Disabled by default.

06 What's inside

Skills

linear-pmEncodes label vocabulary, status taxonomy, branch/PR naming, issue template, and per-repo policy (.claude/linear.yml). Auto-loads when invoking any /linear-* command or asking about Linear workflows. Documents conventions and red flags.

Commands

/linear-initBootstrap this repo: interactively set up Linear team/project, generate .claude/linear.yml with defaults, create standard labels.

/linear-newFile a new Linear issue with Why/What/Acceptance criteria/Notes template. Can auto-fill context from conversation.

/linear-pickAutonomous issue pickup: validate spec, propose plan (review-only) or write code, verify, open PR (allowed mode). Respects autonomy setting.

/linear-statusRead-only digest of project status: In Progress, In Review, Blocked, Ready queue, Recently shipped. No Linear or git writes.

/linear-syncBackfill Linear state when work started manually: parses issue key from branch name, posts comment, moves status, removes agent-ready.

/linear-blockManually mark issue blocked with reason. Adds agent-blocked label and posts comment. Prevents /linear-pick pickup.

CLI

bootstrap.shValidates prerequisites: git, gh CLI, auth, .claude/linear.yml, required config keys, helper scripts. Idempotent. Prints exact fix commands for each gap. Run: ./.claude/skills/linear-pm/scripts/bootstrap.sh

load-config.shHelper sourced by all /linear-* commands. Loads .claude/linear.yml, exports TEAM/PROJECT/BRANCH_PREFIX/AUTONOMY/VERIFY/etc. as env vars. Used internally by commands.

make-slug.shConverts issue title to kebab-case slug (~40 chars, [a-z0-9-]). Used by /linear-pick to generate branch names.

parse-issue-key.shExtracts Linear issue key (e.g., ABH-123) from branch name. Used by /linear-sync and /linear-block for key inference.

Agents

polling agentOptional external agent that wakes on interval_minutes and runs /linear-pick when poll.enabled: true in .claude/linear.yml. Respects autonomy and verify settings.

Explore the other plugins

Second Wind

Run Claude overnight; auto-resume after 5-hour limit resets

Open guide→

prompt-craft

Sharpen rough prompts into specs, suggest follow-up commands

Open guide→

ios-dev

Build iOS apps, screenshot remotely, release to App Store

Open guide→

core-workflow

Opinionated dev workflow: commit + share + team up

Open guide→

Browse the full skills & tools catalog →