Linear setup

Linear Setup

You have a lot of repos and one brain. This skill sets up Linear so it doesn't fight you.

The approach: one team, one label group, custom views. Not because it's the only way — because it's the right starting point for someone shipping across many projects without a big org chart.

The philosophy

Linear's concepts don't map 1:1 to how a solo dev with many repos works:

Linear concept	What it actually is	What you might assume
Team	Group of people with shared workflow	A repo or product
Project	Time-bound feature/initiative	A repo or product
Label	Flexible tag	—
Custom View	Saved filter	—

The fix: use one team as your workspace, a "Product" label group to tag which repo/product each issue belongs to, and custom views filtered by label to get per-product boards when you need them.

When to run this

• First time setting up Linear for multi-repo work
• Adding a batch of new repos to an existing setup
• Reorganizing after things got messy
• Someone asks "how should I organize Linear?"

Step 1: Discover the workspace

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

Understand what's already there. If there's already one team — great, use it. If there are multiple teams, ask whether they want to consolidate or keep the structure.

Step 2: Discover repos

If the user works in a GitHub org, discover their repos:

gh repo list <ORG> --limit 100 --json name,description,isArchived,pushedAt --jq '[.[] | select(.isArchived == false)] | sort_by(.pushedAt) | reverse'

If no org, check personal repos or ask the user to list what they're working on.

Sort by recent activity. Not every repo needs a label — just the ones with active or upcoming work.

Step 3: Propose the label group

Present a table of recommended product labels based on active repos:

Product labels to create:

Label	Based on	Recent activity
my-project	my-project repo	2 days ago
cool-tool	cool-tool repo	5 days ago
website	org.github.io	1 week ago

Skipping (no recent activity):

• old-experiment (3 months ago)
• archived-thing (6 months ago)

You can always add more labels later. Want me to create these?

Use the repo name as-is for the label (lowercase, hyphenated). Don't title-case — labels should match folder names for easy mental mapping.

Wait for confirmation before creating anything.

Step 4: Create the label group

Linear's label groups make labels mutually exclusive within the group — exactly right for "which product is this issue about."

# First create the Product group
linctl label create --team <TEAM_KEY> --name "Product" --is-group

# Then create each product label as a child
linctl label create --team <TEAM_KEY> --name "<repo-name>" --parent "Product" --color "<color>"

Also create the Seed label — the linear-seed skill uses it to tag raw ideas:

linctl label create --team <TEAM_KEY> --name "Seed" --color "#86EFAC"

Color assignment: Use soft pastels with maximum hue separation so products are instantly distinguishable on a board:

Color	Hex
Rose	#F9A8D4
Peach	#FDBA74
Lemon	#FDE68A
Mint	#86EFAC
Sky	#7DD3FC
Lavender	#C4B5FD
Lilac	#D8B4FE
Coral	#FCA5A5
Seafoam	#99F6E4
Periwinkle	#A5B4FC

Cycle through these starting from rose. Ten distinct hues covers most setups. If there are more products than colors, repeat the cycle — Linear's label chips are small enough that duplicates across distant products won't cause confusion.

Step 5: Check existing labels

Look at what labels already exist. Common situations:

Type labels already exist (Bug, Feature, Improvement): Keep them. They serve a different purpose than product labels — type describes what kind of work, product describes where.

Domain labels exist (Frontend, Backend, Audio, etc.): Keep them too if they're useful. These are a third axis. An issue can be guitarjournal + Feature + Audio.

Repo-like labels already exist but not in a group: Offer to move them into the new Product group for consistency.

Step 6: Suggest custom views

After labels are created, suggest creating favorited views for the most active products:

Suggested views:

• "my-project" → filtered to Product: my-project
• "cool-tool" → filtered to Product: cool-tool

Pin these to your sidebar for quick access. Want me to walk you through creating them?

Custom views are created in the Linear UI (not via API/CLI), so provide the filter instructions:

1. Click "+" in the sidebar under Views
2. Filter by Label → Product → [repo-name]
3. Save and favorite

Step 7: Rename workflow statuses (optional)

Linear's default statuses are fine but generic. If the user wants something with more personality, offer to rename them.

The magpie-recommended statuses:

Category	Default	Recommended	Color	Description
Backlog	(create in UI)	Seeds	#E8E5DF (beige)	Raw ideas — dormant, waiting to germinate
Backlog	Backlog	Soil	#5C5C5C (dark gray)	Real work, planted, waiting for its season
Unstarted	Todo	Ready	#C49A3C (gold)	Ready to pick up
Started	In Progress	Growing	#8B9E7E (sage)	The work is alive
Started	In Review	Ripening	#9B8EA8 (mauve)	Fruit's on the vine, seeing if it's ready
Completed	Done	Harvested	#C2714F (terra cotta)	You grew it, you picked it, it's done
Cancelled	Cancelled	Composted	#6B3A2A (dark brown)	Went back to the earth — fertilizer, not failure
Cancelled	Duplicate	Duplicate	—	Keep as-is

Important: A default Linear team only has ONE backlog state (Backlog). The Seeds state must be created manually in the Linear UI first — linctl can only rename existing states, not create new ones.

Walk the user through this before running the rename commands:

Before I rename states, you'll need to create one new state in the Linear UI:

1. Go to Team Settings → Workflow
2. In the Backlog section, click + Add status
3. Name it anything (we'll rename it via CLI)
4. Let me know when it's there

First, list the current workflow states to get their IDs:

linctl team state list <TEAM_KEY> --json

Then rename each state with its description and color. Always include --color — omitting it leaves the Linear default grays, which look wrong for the botanical names:

linctl team state update <STATE_ID> --name "Seeds" --color "#E8E5DF" --description "Raw ideas — dormant, waiting to germinate"
linctl team state update <STATE_ID> --name "Soil" --color "#5C5C5C" --description "Real work, planted, waiting for its season"
linctl team state update <STATE_ID> --name "Ready" --color "#C49A3C" --description "Ready to pick up"
linctl team state update <STATE_ID> --name "Growing" --color "#8B9E7E" --description "The work is alive"
linctl team state update <STATE_ID> --name "Ripening" --color "#9B8EA8" --description "Fruit's on the vine, seeing if it's ready"
linctl team state update <STATE_ID> --name "Harvested" --color "#C2714F" --description "You grew it, you picked it, it's done"
linctl team state update <STATE_ID> --name "Composted" --color "#6B3A2A" --description "Went back to the earth — fertilizer, not failure"

See plugins/linear/LINCTL_REFERENCE.md for exact command syntax and gotchas.

Leave "Duplicate" as-is — it's already descriptive.

This is a one-time setup. Ask before renaming — not everyone wants botanical workflow vibes.

Step 8: Recap

Summarize what was set up:

Your Linear workspace is ready:

• Team: [team name] (your single workspace)
• Product labels: [count] labels in the "Product" group
• Type labels: Bug, Feature, Improvement (unchanged)
• Workflow: Seeds → Soil → Ready → Growing → Ripening → Harvested (if renamed)
• Next step: When you create issues, tag them with the right product label. The linear-workflow skill does this automatically based on which repo you're working in.

To add a new product label later:

linctl label create --team <KEY> --name "new-repo" --parent "Product" --color "#hex"

Escape hatch: promoting to a Team

When a product outgrows labels — needs its own workflow states, cycles, or dedicated board — promote it to its own Team:

1. Create a new team in Linear
2. Move issues with that product label to the new team
3. Remove the product label (the team now serves that purpose)
4. Update the GitHub integration if needed

This is a one-way door that's easy to walk through when you need it. Don't do it preemptively.

Edge cases

User already has multiple teams: Don't force consolidation. Ask if the current structure is working. If they want to simplify, help migrate issues to a single team first.

User has no GitHub org (personal repos): Use gh repo list --json name,pushedAt without an org flag, or just ask them to list their active projects.

User wants teams, not labels: That's valid for larger operations. Explain the tradeoff (sidebar bloat, no unified "my week" view) and help set up whichever they prefer.

User wants to track non-code products: Labels work for anything — "writing", "music", "admin". They don't have to map to GitHub repos. Ask what they're tracking and create labels accordingly.