Linear

Linear

BLOCKING skill that intercepts ALL Linear operations via linearis CLI to enforce:

• Issues assigned to the configured user
• Due dates always requested
• Team/project inferred from conversation context

CLI Tooling

linearis CLI

All Linear operations use the linearis CLI which outputs JSON:

linearis issues create "<title>" -d "<desc>" -a <YOUR_LINEAR_USER_UUID> -p <N> --team <KEY> --project "<name>" --labels "<labels>"
linearis issues search "<query>" --assignee <YOUR_LINEAR_USER_UUID> --team <KEY> --status "<states>" -l 25
linearis issues list -l 25
linearis issues read <IDENTIFIER>
linearis issues update <IDENTIFIER> -s "<status>" -p <N> --labels "<labels>"

User UUID

Set your Linear user UUID in linear-context.json under user.id. Use this UUID instead of "me" for all assignee operations for reliable results.

GraphQL Helper (Due Date & Estimate)

linearis does not support --due-date or --estimate flags. Use the GraphQL helper bundled in this plugin:

${CLAUDE_PLUGIN_ROOT}/skills/linear/tools/linear-graphql.sh set-due-date "<issueUUID>" "YYYY-MM-DD"
${CLAUDE_PLUGIN_ROOT}/skills/linear/tools/linear-graphql.sh set-estimate "<issueUUID>" <points>
${CLAUDE_PLUGIN_ROOT}/skills/linear/tools/linear-graphql.sh set-due-date-and-estimate "<issueUUID>" "YYYY-MM-DD" <points>

Requires LINEAR_API_TOKEN in environment or ~/.env.secrets.

Important CLI Notes

• linearis issues list has NO filters — use linearis issues search for all filtered queries
• linearis issues search supports --team, --assignee, --project, --status, -l
• linearis issues update accepts both UUID and identifiers (e.g., <TEAM>-165)
• Due date/estimate changes require the issue UUID (not identifier) — read the issue first to get it

Workflow Routing

Examples

Example 1: Create a new issue

User: "Create an issue to update the API documentation"
-> Invokes CreateIssue workflow
-> Infers team from context or prompts
-> Prompts for due date
-> Assigns to configured user UUID
-> Creates issue via linearis CLI + GraphQL helper for due date

Example 2: List current tasks

User: "What issues do I have in my backlog?"
-> Invokes ListIssues workflow
-> Searches with --assignee UUID
-> Fetches issues across all teams
-> Formats with priority indicators

Example 3: Close a completed task

User: "Mark <TEAM>-165 as done"
-> Invokes CloseIssue workflow
-> Identifies issue by identifier
-> Updates status to "Done" via linearis issues update

Example 4: Resolve an issue end-to-end

User: "Resolve <TEAM>-200"
-> Fetches issue, looks up repo from linear-context.json
-> Creates feature branch, updates status to In Progress
-> Architect agent investigates codebase, proposes TDD strategy
-> Engineer agent writes failing tests, then implements solution
-> Commits, pushes, creates PR with issue reference
-> Monitors CI, fixes any failures via subagent
-> CI passes: immediately attempts merge (squash, delete branch)
-> If merge blocked: attempts self-approve, then merges
-> Only pauses if external reviewer required (re-enter with /resolve <TEAM>-200)
-> On approval: merges PR, closes Linear issue to Done

Example 5: Plan a new feature as issues

User: "Break down the search feature into issues"
-> Invokes PlanProject workflow
-> Decomposes feature using First Principles thinking
-> Creates 5 issues with max 3 acceptance criteria each
-> Sets dependencies, priorities, and estimates
-> Batch-creates in Linear after user approval

Example 6: Daily shipping workflow

User: "What should I work on today?"
-> Invokes ShipDaily workflow
-> Fetches open issues sorted by priority + due date
-> Presents top 3 candidates for selection
-> Triggers ResolveIssue for each selected issue
-> Reports daily shipping summary

Example 7: Check CI on a PR

User: "Is CI passing on <TEAM>-200?"
-> Invokes MonitorCI workflow
-> Checks GitHub Actions status for the feature branch
-> Reports: passing/failing with details

Example 8: Handle PR review feedback

User: "Address the review comments on <TEAM>-200"
-> Invokes ReviewPR workflow
-> Reads all review comments from GitHub
-> Spawns subagent to address each comment
-> Commits fixes, pushes, reports status

Validation Rules (ENFORCED)

On Issue Creation - MANDATORY CHECKLIST

ALL fields must be populated. No partial issues.

Workflow:

1. Parse user request for project context triggers
2. Match to project using linear-context.json
3. If no match -> ASK user which project (use AskUserQuestion)
4. Prompt for due date if not provided
5. Set priority (default: 3=Normal)
6. Create issue with linearis CLI, then set due date/estimate via GraphQL helper

On Issue Update

1. Track what changed

On Issue Close

1. Verify completion

Team Routing

All issues route to the default team configured in linear-context.json. The defaultTeamKey field in the routing section determines which team key is used.

Project Inference

The skill infers project from conversation context using triggers in linear-context.json. Each project entry has a triggers array of keywords. If no project match is found, ASK the user which project (use AskUserQuestion).

Label Inference

Gotchas

• linearis CLI outputs JSON by default — do NOT add --json flag. It doesn't exist and errors out.
• Project descriptions have a 255 character limit. Truncate before sending.
• Multiline issue descriptions can cause JSON parse errors when extracting issue IDs. Use head -3 for id extraction from linearis output.
• Due dates must be set via GraphQL: ${CLAUDE_PLUGIN_ROOT}/skills/linear/tools/linear-graphql.sh set-due-date

Reference Documentation

• linear-context.json - Your workspace data: teams, projects, triggers, IDs (copy from linear-context.example.json and populate)
• LinearContext.md - Workflow documentation and examples