Linear Workflow

Linear Workflow

You collect ideas like a magpie. This skill catches them and puts them somewhere real.

When the user describes work — building something, fixing something, wanting something — create a Linear issue for it. No forms, no ceremony. Draft it from context, confirm, file it.

Command reference

All linctl commands used by this skill are documented in plugins/linear/LINCTL_REFERENCE.md. Read it before running any linctl commands — it has exact flags and gotchas that prevent wasted calls.

First things first — discover the workspace via subagent

At session start, delegate workspace discovery to a background subagent. This is ~4 calls that only need to happen once, and they shouldn't eat the main context window.

1. Use the Agent tool with subagent_type="general-purpose" and run_in_background=true
2. Include in the prompt:
   • The full text of plugins/linear/LINCTL_REFERENCE.md
   • Instructions to run: linctl whoami, linctl team list --json, linctl project list --team <KEY> --newer-than all_time --json, linctl label list --team <KEY> --json
   • Ask it to return: team key, list of projects, list of labels
3. Cache the results for the session. If there's only one team, use it automatically. If there are multiple, ask the user which one to use for this repo.

How projects map to repos

The repo's folder name maps to a Linear project name by converting hyphens to spaces and title-casing:

Look up whether a matching project exists. If not, ask: "There's no Linear project for this repo yet. Want me to create one?"

When creating a new project, do it explicitly before creating any issues:

# Step 1: Create the project
linctl project create --name "My Project" --team <TEAM_KEY> --state started

# Step 2: Now create issues in it
linctl issue create --title "..." --team <TEAM_KEY> --project "My Project" ...

Don't assume --project on issue create will auto-create a project — it won't. The project must exist first.

When to create issues

This includes:

• Explicit: "let's build a login page", "create a ticket for the auth bug"
• Implicit: "the sidebar is broken", "we need better error messages", "it would be nice to have dark mode"

Before creating, briefly confirm what you're about to file: the title, labels, and (if not obvious) a one-line description. Don't make the user fill out a form — draft it from context and let them correct.

After confirmation, delegate the creation to a background subagent:

1. Use the Agent tool with subagent_type="general-purpose" and run_in_background=true
2. Include in the prompt:
   • The full text of plugins/linear/LINCTL_REFERENCE.md
   • The issue details (title, team key, project, labels, description, --assign-me if appropriate)
   • If the project doesn't exist yet, instruct the subagent to create it first with linctl project create
3. Report back with the issue identifier

Labels

Fetch labels at the start of each session:

linctl label list --team <TEAM_KEY> --json

Pick the most relevant labels from what's available. Most issues get one type label (Bug, Feature, Improvement) and optionally one domain label if the team has them.

If the work doesn't fit existing labels, suggest a new one: "This feels like it needs an 'Infrastructure' label — want me to create it?"

linctl label create --team <TEAM_KEY> --name "Infrastructure" --color "#8B5CF6"

Working on existing issues

When starting work on something that already has a ticket, move it to "Growing":

linctl issue update <ISSUE_ID> --state "Growing" --assignee me

When done:

linctl issue update <ISSUE_ID> --state "Harvested"

Attach PRs when relevant:

linctl issue attach <ISSUE_ID> --pr https://github.com/org/repo/pull/123

What's ready?

When the user asks "what should I work on next", "what's ready", or "what's on the board" — delegate the query to a background subagent, then present results by priority.

1. Use the Agent tool with subagent_type="general-purpose" and run_in_background=true
2. Include in the prompt:
   • The full text of plugins/linear/LINCTL_REFERENCE.md
   • Instructions to run linctl issue list --team <TEAM_KEY> --state "Ready" --json
   • The current repo's folder name (for filtering by product label)
   • Ask it to return the filtered, priority-sorted results

Filter the results to issues with a product label matching the current repo's folder name (e.g., in the magpie repo, filter to issues labeled magpie). Then sort by priority — 1 (Urgent) first, 4 (Low) last, 0 (None) at the end.

Present them as a short list:

Ready to pick up (magpie):

1. MZR-87 update linear-setup to use linctl for status renaming (Normal)
2. MZR-88 add status descriptions to linear-setup workflow (Normal)
3. MZR-89 decide on .claude/ and linear-seed-workspace/ in repo (Normal)

Want to start one? I'll move it to Growing and assign it to you.

If there are no Ready issues for this repo, say so. If there are Ready issues without a product label, mention them separately — they might be cross-cutting work.

When the user picks one, move it to Growing and assign:

linctl issue update <ISSUE_ID> --state "Growing" --assignee me

Checking the board

For a broader view beyond just Ready issues, delegate to a background subagent:

1. Use the Agent tool with subagent_type="general-purpose" and run_in_background=true
2. Include in the prompt:
   • The full text of plugins/linear/LINCTL_REFERENCE.md
   • Instructions to run linctl issue list --team <TEAM_KEY> --state "Growing" --json and linctl issue list --assignee me --newer-than all_time --json
   • Ask it to return results grouped by state

Present results grouped by state. Include Linear links when available.

Issue titles

Write titles the way you'd describe the work to a friend — lowercase, concise, action-oriented:

• "add dark mode support"
• "fix sidebar overflow on mobile"
• "improve error messages in auth flow"

No Jira-speak. No "As a user, I want to...". Just what needs doing.

When NOT to create issues

• Quick one-off questions ("what does this function do?")
• Exploratory conversation that hasn't landed on concrete work yet
• The user explicitly says they don't want to track something

If you're unsure whether something warrants a ticket, lean toward asking: "Want me to track this in Linear?"